-
Notifications
You must be signed in to change notification settings - Fork 68
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.
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
Improve Swagger with examples in POST operations #153
Comments
I second this. I had to do a fair amount of digging to find out exactly what kind of JSON blob REMReM expected. Eventually I found https://eiffel-community.github.io/eiffel-remrem-generate/serviceUsage.html. |
Magnus , Can please tell exactly which JSON example are you referring to ,in the link which you have provided? |
The Usage section of https://eiffel-community.github.io/eiffel-remrem-generate/serviceUsage.html contains a table with all the REST endpoints and the following example for /mp:
For a first-time user this isn't entirely easy to find, although the recently completed (?) migration from GitHub Pages to plain markdown files in the git should improve the situation quite a bit. I suspect it's something like the above that the issue creator is looking for. |
Yes, @magnusbaeck those kind of examples are what I was referring to when I created the issue. It would be very helpful for users trying out the REST API if there examples ready to use already in the Swagger GUI. |
Adding examples to a property does not seem to work atm in springfox-swagger. Its been a known issue for a while as can be seen here: springfox/springfox#2873 |
We tried with some approaches, but no use. |
This has been closed without a fix springfox/springfox#2873 so how to proceed further on this ? |
This may have been fixed through springfox/springfox#2767 and is part of 3.0.0 so I think this can be investigated again. |
Description
The Swagger interface of REMReM generate 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 generate.
Exemplification
Currently we have:
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.
The text was updated successfully, but these errors were encountered: