Improve Swagger with examples in POST operations

e-pettersson-ericsson commented 4 years ago

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.

magnusbaeck commented 4 years ago

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.

iamrishavkumar commented 4 years ago

Magnus , Can please tell exactly which JSON example are you referring to ,in the link which you have provided?

magnusbaeck commented 4 years ago

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:

{
  "msgParams": {
    "meta": {
      # Matches the meta object
    }
  },
  "eventParams": {
    "data": {
      # Matches the data object
    },
    "links": {
      # Matches the links object
    }
  }
}

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.

e-pettersson-ericsson commented 4 years ago

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.

Christoffer-Cortes commented 4 years ago

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: https://github.com/springfox/springfox/issues/2873 There may be a workaround to this or simply a different approach.

raja-maragani commented 4 years ago

We tried with some approaches, but no use. Perhaps we should wait for springfox 3.0.0 release.

SantoshNC68 commented 4 years ago

This has been closed without a fix https://github.com/springfox/springfox/issues/2873 so how to proceed further on this ?

Christoffer-Cortes commented 4 years ago

This may have been fixed through https://github.com/springfox/springfox/issues/2767 and is part of 3.0.0 so I think this can be investigated again.

eiffel-community / eiffel-remrem-generate