How not to copy-paste 3 generic error responses in almost all paths?

by

OpenAPI 2.0 (fka Swagger 2.0)

Looks like I can add the following global response definition:

# An object to hold responses that can be used across operations.
# This property does not define global responses for all operations.
responses:
  NotAuthorized:
    description: The requester is unauthorized.
    schema:
      $ref: '#/definitions/Error'

However I will still need to reference it in paths like this:

401:
  $ref: '#/responses/NotAuthorized'

OpenAPI 3.x

Same thing in OpenAPI 3.x, except it uses #/components/responses/... instead of #/responses/...:

openapi: 3.0.0

# An object to hold responses that can be used across operations.
# This property does not define global responses for all operations.
components:
  responses:
    NotAuthorized:
      description: The requester is unauthorized.
      schema:
        $ref: '#/components/schemas/Error'

# Then, in operation responses, use:
...
401:
  $ref: '#/components/responses/NotAuthorized'

There’s also an open feature request in the OpenAPI Specification repository to add support for global/default responses for operations.

More Related Contents:

  1. Swagger: How to have a property reference a model in OpenAPI 2.0 (i.e. nest the models)?
  2. How to specify if a field is optional or required in OpenAPI/Swagger?
  3. How to return an array of objects in SwaggerHub?
  4. How to document dynamic query parameter names in OpenAPI (Swagger)?
  5. How to define a mixed-type array (with different element types) in OpenAPI 2.0?
  6. How to define a property that can be string or null in OpenAPI (Swagger)?
  7. Swagger schema properties ignored when using $ref – why?
  8. How to define mutually exclusive query parameters in Swagger (OpenAPI)?
  9. Swagger 2.0: Multiple Path objects with different paths but same request and response
  10. Swagger/OpenAPI – use $ref to pass a reusable defined parameter
  11. How to convert OpenAPI 2.0 to OpenAPI 3.0? [closed]
  12. Swagger: wildcard path parameters
  13. How to define an optional parameter in path using swagger
  14. Swagger: “equivalent path already exists” despite different parameters
  15. Re-using model with different required properties
  16. How to write OpenAPI 3 (Swagger) specification for property name in `map` object?
  17. How to define global parameters in OpenAPI?
  18. Schema object without a type attribute in Swagger 2.0
  19. Swagger: take one or more values from enum
  20. Swagger Inheritance and Composition
  21. Swagger/OpenAPI mock server
  22. Swagger: map of
  23. Use object type query param in swagger documentation
  24. Swagger complex response model with dynamic key value hash maps
  25. How do I include subclasses in Swagger API documentation/ OpenAPI specification using Swashbuckle?
  26. OpenAPI query string parameter with list of objects
  27. OpenAPI path/query parameters nested structure serialization
  28. Combining defintions in Swagger docs
  29. How to document default None/null in OpenAPI/Swagger using FastAPI?
  30. How do I combine multiple OpenAPI 3 specification files together?

Leave a Comment