Graylog2 / Graylog2/graylog2-server
REST API docs: Provide attribute example hints
- 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.

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
Assessment
This issue has not been assessed yet.