Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve Swagger with examples in POST operations #182

Open
e-pettersson-ericsson opened this issue Nov 25, 2019 · 0 comments
Open

Improve Swagger with examples in POST operations #182

e-pettersson-ericsson opened this issue Nov 25, 2019 · 0 comments
Labels
code improvements Improvements to make the code base more readable and manageable. documentation Improvements or additions to the documentation.

Comments

@e-pettersson-ericsson
Copy link
Member

Description

The Swagger interface of REMReM publish should have proper examples of JSON structures in the POST requests. Right now these endpoints have a big blob of irrelevant JSON which does not help the user prepare a body for the HTTP request. I want to replace the default JSON blob with the correct JSON body.

This could be achieved for example by defining JSON schemas to show how the JSON object should look like and what fields are required/optional etc. I did a quick google search and found it is possible to define JSON schemas using Swagger, https://swagger.io/docs/specification/describing-request-body/

Motivation

Easier to start playing around with the REST API of REMReM publish.

Exemplification

Currently we have:
image

But I would like a proper example of accurate JSON which could immediately be copied and used. So the yellow box would contain an example value which is actually useful.

Benefits

More useful Swagger description of the interface.

Possible Drawbacks

None that I can think of.
@e-pettersson-ericsson e-pettersson-ericsson added enhancement New or extended features. documentation Improvements or additions to the documentation. labels Nov 25, 2019
@SantoshNC68 SantoshNC68 added the code improvements Improvements to make the code base more readable and manageable. label Nov 27, 2019
@e-pettersson-ericsson e-pettersson-ericsson removed the enhancement New or extended features. label Jan 22, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
code improvements Improvements to make the code base more readable and manageable. documentation Improvements or additions to the documentation.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@SantoshNC68 @e-pettersson-ericsson