Skip to content
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

[REQ] Addition of API response examples #17610

Open
GlobeDaBoarder opened this issue Jan 14, 2024 · 0 comments · May be fixed by #17613
Open

[REQ] Addition of API response examples #17610

GlobeDaBoarder opened this issue Jan 14, 2024 · 0 comments · May be fixed by #17613

Comments

@GlobeDaBoarder
Copy link

GlobeDaBoarder commented Jan 14, 2024

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 Request
    content:
      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: 400
        message: name size must be between 0 and 50
    DogNameContainsNumbersError:
      value:
        code: 400
        message: Name must contain only letters
    DogAgeNegativeError:
      value:
        code: 400
        message: 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:

image

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.

image

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

Describe alternatives you've considered

Additional context

Related issue: #16051

Related PR: #17613

Demonstration spec file with response examples: openapi.yaml

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
1 participant