swagger-api / swagger-parser

Swagger Spec to Java POJOs
http://swagger.io
Apache License 2.0
773 stars 525 forks source link

Reusable examples not being resolved #2098

Closed dbr-cbk closed 1 month ago

dbr-cbk commented 1 month ago

Hello, It seems that the library is not able to correctly resolve the reusable examples (defined under "/components/examples"). When setting "setResolve(true)" and "setResolveFully(true)", it still maintains the references to the examples, instead of replacing the references. If these example components are defined in a separate file, it doesn't even include them in the resulting yaml.

When processing the following yaml with both properties set to "true":

openapi: 3.0.1
info:
  title: Swagger Petstore - OpenAPI 3.0
  version: 1.0.11
paths:
  /pet:
    put:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'          
components:
  examples:
    DogName:
      value:
        name: "Tobby"
        surname: "Smith"
  schemas:
    Pet:
      type: object
      properties:
        name:
          type: object
          properties:
            name:
              type: string
              description: name desc
            surname:
              type: string
              description: surname desc
          example:
            $ref: '#/components/examples/DogName'

it produces the following result:

openapi: 3.0.1
info:
  title: Swagger Petstore - OpenAPI 3.0
  version: 1.0.11
servers:
- url: /
paths:
  /pet:
    put:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: object
                  properties:
                    name:
                      type: string
                      description: name desc
                    surname:
                      type: string
                      description: surname desc
                  example:
                    $ref: '#/components/examples/DogName'
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: object
                    properties:
                      name:
                        type: string
                        description: name desc
                      surname:
                        type: string
                        description: surname desc
                    example:
                      $ref: '#/components/examples/DogName'
components:
  schemas:
    Pet:
      type: object
      properties:
        name:
          type: object
          properties:
            name:
              type: string
              description: name desc
            surname:
              type: string
              description: surname desc
          example:
            $ref: '#/components/examples/DogName'
  examples:
    DogName:
      value:
        name: Tobby
        surname: Smith

Furthermore, when the example is defined in a separate file, the reference is retained (as demonstrated in this snippet); however, the component is not included in the resulting contract's components structure, thereby resulting in broken references.

dbr-cbk commented 1 month ago

My bad. According to OpenAPI spec (Reusable examples), it is not possible to include references under "example" structure. It is supported under "examples" instead.