Improve Swagger with examples in POST operations

[e-pettersson-ericsson]

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]

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]

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

[magnusbaeck]

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]

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]

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
There may be a workaround to this or simply a different approach.

[raja-maragani]

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

[SantoshNC68]

This has been closed without a fix springfox/springfox#2873 so how to proceed further on this ?

[Christoffer-Cortes]

This may have been fixed through springfox/springfox#2767 and is part of 3.0.0 so I think this can be investigated again.