Graylog2 / Graylog2/graylog2-server

REST API docs: Provide attribute example hints

Open
#6,887 1 comment 0 reactions 0 assignees View on GitHub
content-packs feature triaged
Dominant language
Java
Stars
8.1k
Forks
1.1k
Avg merge
1d 20h
Merged PRs (30d)
217

Description

## What?

- Add more hints for parameters, or actual examples how they should look like.
- The Java native generated output does not clearly tell about objects being a hash/dictionary

## Why?

If you're not a Java developer, the body parameters are somewhat trial and error. In this case, I am trying to install an uploaded content pack. "installation request" needs to be populated in the body.

Screen Shot 2019-11-28 at 11 42 24

Reading the source code shows some insights, it is still hard to guess that an object for instance is a dictionary/hash.

https://github.com/Graylog2/graylog2-server/blob/master/graylog2-server/src/main/java/org/graylog2/rest/resources/system/contentpacks/ContentPackResource.java#L281

The final value then should look like this:

```
{
"parameters": {},
"comment": ""
}
```

This is just an example, other API endpoints would need that as well :)

I'm not saying that one should write documentation, this probably can be added as code attribute such as `hint` or similar, which is shown in the web REST API console then.

## Your Environment

* Graylog Version: 3.1.3
* Elasticsearch Version: 6.8.5
* MongoDB Version: 4.0.0
* Operating System: CentOS 7
* Browser version: 78.0.3904.108

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.