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

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 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.

Answer 2

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