OpenAPITools / OpenAPITools/openapi-generator

[BUG][SPRING] response examples: uncompilable output, unsupported example types

Open
#21,178 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Issue: Bug
Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

Support for api response examples has been added to Spring generator in #20933 - i.e. in OpenAPI Generator 7.13.0. As discussed in this PR, there are still some known limitations to the current implementation:

  • Conversion of examples to strings can lead to uncompilable output due to improper escaping:
    openapi: 3.0.3
    info:
      title: No examples in annotation example API
      version: 1.0.0
    paths:
      /:
        get:
          summary: Create a dog
          responses:
            '400':
              description: Bad Request
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/Error'
                  examples:
                    dog age negative:
                      $ref: '#/components/examples/DogAgeNegativeError'
    
    components:
      schemas:
        Error:
          type: object
          properties:
            message:
              type: string
      examples:
        DogAgeNegativeError:
          value:
            message: '"' # <--- encoding problem here
    
  • Only the examples keyword is supported, but not the example (singular) keyword:
    openapi: 3.0.3
    info:
      title: No examples in annotation example API
      version: 1.0.0
    paths:
      /:
        get:
          summary: Create a dog
          responses:
            '400':
              description: Bad Request
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/Error'
                  example: # <--- not recognized
                    message: my description
    components:
      schemas:
        Error:
          type: object
          properties:
            message:
              type: string
    
  • specifying examples inside the component schemas isn't supported
    openapi: 3.0.3
    info:
      title: No examples in annotation example API
      version: 1.0.0
    paths:
      /:
        get:
          summary: Create a dog
          responses:
            '400':
              description: Bad Request
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/Error'
    
    components:
      schemas:
        Error:
          type: object
          properties:
            message:
              type: string
          example: # <--- not supported
            message: my example string
    
  • specifying examples in this alternative way shown in the spec results in empty names and no descriptions

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading PR #20933 and reproducing the listed response-example cases in the Spring generator. Check generated output for escaping, singular and schema examples, and alternative Example Object metadata; done means the examples are represented correctly and the generated output compiles.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi, spring
Domain
api, devtools
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.