You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Is your feature request related to a problem? Please describe.
Yes, not having API response examples is quite limiting in how we can express and document an API.
Imagine a scenario: we have a simple endpoint that can return several types of 400 HTTP responses based on different validation violations that might occur. For example "age can't be negative" and "name can't contain numbers". Both are a type of 400 response and both would return the same schema object like ErrorDto or something but would have different contents and different error messages.
How can we document and represent that in openapi spec and Swagger UI?
We can do that by specifying response examples that might occur:
....'400':
description: Bad Requestcontent:
application/json:
schema:
$ref: '#/components/schemas/Error'examples:
dog name length:
$ref: '#/components/examples/DogNameBiggerThan50Error'dog name contains numbers:
$ref: '#/components/examples/DogNameContainsNumbersError'dog age negative:
$ref: '#/components/examples/DogAgeNegativeError'
...
And in the components part of the spec we would specify the examples:
examples:
DogNameBiggerThan50Error:
value:
code: 400message: name size must be between 0 and 50DogNameContainsNumbersError:
value:
code: 400message: Name must contain only lettersDogAgeNegativeError:
value:
code: 400message: age must be greater than or equal to 0
As a result, the propper interpretation of the openapi spec and Swagger UI representations shoudl look something like this:
With a drop-down menu of all the examples we have. Upon selecting which, we can see the exact type of data returned below in the example value section.
Unfortunately, Openapi Generator does not have the functionality of generating response examples yet
From what I understand this has been a consideration for improvement for quite some time. As mentioned by @emajo in a related issue addressing this problem (#16051), there's even a TODO in the DefaultCodegen class addressing that issue
Why this is needed and an essential addition?
As you can see, having response examples can provide a very essential and important details and context to the documentation fo your API.
Speaking from personal experience, and the whole reason why I decided to address this issue, I noticed that in our team front-end developers and newcomers to the back-end team always asked us back-end developers "What exact types of 400 errors can u receive" and we would usually have to reference them to external business documentation to just explain from our business logic what kind of validation errors can occur. And having those things all in one in Swagger UI would be great. Front-end developers can take a look at the endpoints they need to integrate and immediately see what kind of exceptional scenarios can occur and how to properly handle them on the front-end side. Speaking even more generally, a newcomer to the back-end team or even a BA or PM, or whoever wanting to take a look at the API documentation would get a much clearer and better picture of the behavior and minor details of the API.
Describe the solution you'd like
First of all, I thought this was just an api.mustache issue from the spring generator, which I am using primarily. However, I later found a related issue and realized that this is a bigger scope. The DefaultCodegen does not process API response examples in any shape or form. So, to address this, the behavior of the generator itself as well as templates for generators (spring in my case) have to be adjusted
The solution is deeply described in the correlated PR made by me to address this issue (#17613).
But describing the main points very shortly:
DefaultCodegenthas been modified to include processing API response examples from the open API spec
a test case checking to see examples generation has been added
api.mustache file for spring generator has been modified to generate@ExampelObject swagger annotations to achieve displaying examples in the swagger UI
Is your feature request related to a problem? Please describe.
Yes, not having API response examples is quite limiting in how we can express and document an API.
Imagine a scenario: we have a simple endpoint that can return several types of
400
HTTP responses based on different validation violations that might occur. For example "age can't be negative" and "name can't contain numbers". Both are a type of400
response and both would return the sameschema
object likeErrorDto
or something but would have different contents and different error messages.How can we document and represent that in openapi spec and Swagger UI?
We can do that by specifying response examples that might occur:
And in the
components
part of the spec we would specify the examples:As a result, the propper interpretation of the openapi spec and Swagger UI representations shoudl look something like this:
With a drop-down menu of all the examples we have. Upon selecting which, we can see the exact type of data returned below in the
example value
section.Unfortunately, Openapi Generator does not have the functionality of generating response examples yet
From what I understand this has been a consideration for improvement for quite some time. As mentioned by @emajo in a related issue addressing this problem (#16051), there's even a TODO in the
DefaultCodegen
class addressing that issueWhy this is needed and an essential addition?
As you can see, having response examples can provide a very essential and important details and context to the documentation fo your API.
Speaking from personal experience, and the whole reason why I decided to address this issue, I noticed that in our team front-end developers and newcomers to the back-end team always asked us back-end developers "What exact types of 400 errors can u receive" and we would usually have to reference them to external business documentation to just explain from our business logic what kind of validation errors can occur. And having those things all in one in Swagger UI would be great. Front-end developers can take a look at the endpoints they need to integrate and immediately see what kind of exceptional scenarios can occur and how to properly handle them on the front-end side. Speaking even more generally, a newcomer to the back-end team or even a BA or PM, or whoever wanting to take a look at the API documentation would get a much clearer and better picture of the behavior and minor details of the API.
Describe the solution you'd like
First of all, I thought this was just an api.mustache issue from the spring generator, which I am using primarily. However, I later found a related issue and realized that this is a bigger scope. The
DefaultCodegen
does not process API response examples in any shape or form. So, to address this, the behavior of the generator itself as well as templates for generators (spring in my case) have to be adjustedThe solution is deeply described in the correlated PR made by me to address this issue (#17613).
But describing the main points very shortly:
DefaultCodegent
has been modified to include processing API response examples from the open API specapi.mustache
file for spring generator has been modified to generate@ExampelObject
swagger annotations to achieve displaying examples in the swagger UIDescribe alternatives you've considered
Additional context
Related issue: #16051
Related PR: #17613
Demonstration spec file with response examples:
openapi.yaml
The text was updated successfully, but these errors were encountered: