Is it possible to 'group' reusable components in open API definitions?

Question

I'm learning to use swagger and am having trouble finding the answer to this.

Let's say for example I have 10 endpoints that all share a group of responses, for example's sake let's say they are:

components:
  responses:
    'success':
      description: Success
    'failed':
      description: Failed
    'unknown':
      description: Unknown
    'dontincludeme':
      description: A status I don't always want to include

Currently, as I understand it I need to reference them as follows in various paths:

paths:
  /start:
    post:
      summary: Start a process
      tags:
        - Process Management
      responses:
        '1':        
         $ref: '#/components/responses/success'
        '2':
         $ref: '#/components/responses/failed'
        '3':
         $ref: '#/components/responses/unknown'

I'm looking for a way to 'group' them so that I can reference for example, 10 different responses at a time for a path. Is this possible? I know I can reference all the responses, but I don't always want to reuse all defined codes for all paths.

Answer 1

You can use the default responses in components element. In this example, 200 code is specific for each request. 4xx are common

paths:    
    "/api/account":
        get:
          ...
          responses:
             200:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/user'
            400:
              $ref: '#/components/responses/BadRequest'
            401:
              $ref: '#/components/responses/Unauthorized'
            403:
              $ref: '#/components/responses/Forbidden'
    ...
components:
    responses:
       BadRequest:
         description: Bad Request
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/Error'
       Unauthorized:
          description: Unauthorized
       Forbidden:
          description: Forbidden
       NotFound:
          description: The specified resource was not found
          content:
            application/json:
               schema:
                  $ref: '#/components/schemas/error'
       InternalError:
          description: Internal error

Answer 2

You can group different responses for the same response HTTP status code as in the example from the OAS3 documentation: https://swagger.io/docs/specification/describing-responses/

But I don't think there is a template to paste a collection of responses with different status codes.

     responses:
        '200':
          description: A JSON object containing pet information
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Cat'
                  - $ref: '#/components/schemas/Dog'
                  - $ref: '#/components/schemas/Hamster'

You could go one further and define a component that contains 'oneOf' those schemas - but you may start to lose legibility.

Another feature you could consider is the default response described in the same document.

     responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        # Definition of all error statuses
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

This will work well if many of the error responses use the same schema. Note that this no longer documents the specific error codes that may be returned by the server - but still gives the client the opportunity to write a generic error handler.