How to show example bodies and responses in uploaded swagger
I've uploaded a swagger 2.0 api definition with examples in the request and response body. In the swagger editor, I have a nice example request and response, with the values from the example request being used by default when I hit "try it out" which reduces the work for the client if they are just trying to get a POC working and don't care about the values.
In the readMe API definition there is no body in the sample code, which makes it really harder to work with. The example response is also ignored (the example is json and the response of the endpoint is defined as application/json) and is instead a big mess of object definitions - see the pysdo code example below.
Swagger editor response | ReadMe response:
{ | [String] name
"name" : "job blogs", | [Object] address
"address" : { | [String] address.street
"street" : "123 fake street", | [String] address.postCode
"postCode" : "123 456", | [Object] address.phoneNumber
"phoneNumber" : { | [int] address.phoneNumber.area
"area" : "123" | [int] address.phoneNumber.number
number: "5555"
}
}
}
This loses a lot of context from the definition (the above example is fairly noddy but in the real code it helps to make the usage, expected charset etc clear), as well as the flow that the given example body produces the given example request.
It appears from the docs that examples are enabled by default https://docs.readme.com/docs/swagger-extensions#section-disable-code-examples
There is already an open feature request for adding examples for required body params https://readmeio.canny.io/feature-requests/p/required-body-params-need-placeholder but this is from two years ago and so may be out of date. Is there a way to add examples for all params, in the body, query and response?
Posted by Olwen Pearce 7 months ago
