Is it possible to combine two responses in OAS v.3

Question

I want to have a combined response of another response and an array of objects for my endpoint like the below example:

{
  access: "string",
  refresh: "string",
  "hospitals": [
    {
      "title": "a hospital",
      "base_url": "hospital.com",
      "secret_key": "68e656b251e67e8358bef8483ab0d51c6619f3e7a1a9f0e75838d41ff368f728"
    }
  ]
}

Below is my token pair response which consists of access and refresh:

responses:
    TokenPairResponse:
        description: generated token pair
        content:
            application/json:
                schema:
                    type: object
                    properties:
                      access:
                        type: string
     
                      refresh:
                        type: string

Also, to create an array of hospitals:

description: user verified successfully
content:
    application/json:
        schema:
            type: object
            properties:
                hospitals:
                    type: array
                items:
                      $ref: "#/components/schemas/Hospital"

Now, I want to know if there is any way to have a combination of array of hospitals and TokenPairResponse in a single response like the abovementioned example.

Update: I've added these to responses:

hospitals:
  description: array of hostpitals
  content:
    application/json:
      schema:
        type: object
        properties:
          hospitals:
            type: array
            items:
              $ref: "#/components/schemas/Hospital"

VerifyUser:
  description: repsonse of user successfull verfication
  content:
    application/json:
      schema:
        allOf:
          - $ref: "#/components/responses/hospitals"
          - $ref: "#/components/responses/TokenPairResponse"

And I've referenced them in my path like this:

responses:
    200:
        description: user verified successfully
        $ref: "#/components/responses/VerifyUser"

This will not render, and I get: no example available

Do you mean `allOf`? See [Combining defintions in Swagger docs](https://stackoverflow.com/q/29463634/113116) — Helen, Jun 08 '20 at 09:01
Yes, but still, I am getting 'no example available'. I will add my current progress as an update to my question. — Winston, Jun 08 '20 at 09:59

score 1 · Accepted Answer · answered Jun 09 '20 at 19:28

allOf can only reference schemas (i.e. #/components/schemas/...) but not response components (#/components/responses/...).

Move your response schemas to the components/schemas section. Then you can define an allOf schema like this:

openapi: 3.0.0
...

components:
  schemas:
    VerifyUser:
      allOf:
        - $ref: "#/components/schemas/Hospitals"    # <---------
        - $ref: "#/components/schemas/TokenPair"    # <---------
    Hospital:
      type: object
      ...
    Hospitals:
      type: object
      properties:
        hospitals:
          type: array
          items:
            $ref: "#/components/schemas/Hospital"
    TokenPair:
      type: object
      properties:
        access:
          type: string
        refresh:
          type: string

  responses:
    hospitals:
      description: array of hostpitals
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Hospitals'
    VerifyUser:
      description: repsonse of user successfull verfication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VerifyUser'
    TokenPairResponse:
      description: generated token pair
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TokenPair'

Thank you for your response. Actually, I wanted to combine two `responses`, not two schemas, mainly because I don't want my schemas part to be cluttered with these kinds of schemas which aren't actually the main models of my project. Although, one way to overcome this problem is by moving these schemas to another file to prevent the mess. — Winston, Jun 14 '20 at 11:02
You can't combine `responses`, `parameters`, `requestBody` components, etc.; you can only combine schemas. — Helen, Jun 15 '20 at 07:32
One of the problems I'm facing is that my component has response headers that I want to combine with a body based component using `allOf`. Do you have any idea how that works and should I keep them in `responses` or `schemas` - it isn't working in `schemas`. — Yatin, Apr 06 '21 at 01:14

Is it possible to combine two responses in OAS v.3

1 Answers1