How to extend a defined response in OpenAPI?

user_16986712 0
Viewed 190

I want to extend the "200SuccessDefault" response with a schema or example.

paths:
  /home:
      ...
      responses:
        200:
          $ref: '#/components/responses/200SuccessDefault'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PieChartElement'
              examples:
                PieChart:
                  $ref: '#/components/examples/PieChart_1'

This approach runs into an error, the schema and examples fields are ignored:

Sibling values alongside $refs are ignored. To add properties to a $ref, wrap the $ref into allOf, or move the extra properties into the referenced definition (if applicable).

I tried allOf:

paths:
  /home:
      responses:
        200:
          allOf:
            - $ref: '#/components/responses/200SuccessDefault'
            - content:
                application/json:
                  schema:
                    type: array
                    items:
                      $ref: '#/components/schemas/PieChartElement'
                  examples:
                    PieChart:
                      $ref: '#/components/examples/PieChart_1'

This approach runs into the error:

should NOT have additional properties additionalProperty: allOf
should have required property 'description' missingProperty: description

swagger openapi
1 Answers

You cannot extend a referenced response object. But, you can use a shared schema object and extend it utilizing allOf within schema.

Inside allOf you can put:

  • your $ref
  • a new type extending your default response

If you want to give an example of an entire extended response (JSON), just put it into "application/json".

An example of OpenAPI would be:

    "202":
      description: Extended response sample
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/application"
              - type: object
                properties:
                  anotherProperty:
                    type: string
                    maxLength: 200
                    example: "Property example"
          example: {id: 1234, anotherProperty: "Hello"}
user_67035300
Related