Welcome to OStack Knowledge Sharing Community for programmer and developer-Open, Learning and Share
Welcome To Ask or Share your Answers For Others

Categories

0 votes
625 views
in Technique[技术] by (71.8m points)

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

I want almost all my paths to have the following 3 generic error responses. How do I describe that in Swagger without copypasting these lines everywhere?

    401:
      description: The requester is unauthorized.
      schema:
        $ref: '#/definitions/Error'
    500:
      description: "Something went wrong. It's server's fault."
      schema:
        $ref: '#/definitions/Error'
    503:
      description: Server is unavailable. Maybe there is maintenance?
      schema:
        $ref: '#/definitions/Error'

Example of how I use this in a request:

paths:
    /roles:
      get:
        summary: Roles
        description: |
          Returns all roles available for users.
        responses:
          200:
            description: An array with all roles.
            schema:
              type: array
              items:
                $ref: '#/definitions/Role'
          401:
            description: The requester is unauthorized.
            schema:
              $ref: '#/definitions/Error'
          500:
            description: "Something went wrong. It's server's fault."
            schema:
              $ref: '#/definitions/Error'
          503:
            description: Server is unavailable. Maybe there is maintenance?
            schema:
              $ref: '#/definitions/Error'
See Question&Answers more detail:os

与恶龙缠斗过久,自身亦成为恶龙;凝视深渊过久,深渊将回以凝视…
Welcome To Ask or Share your Answers For Others

1 Answer

0 votes
by (71.8m points)

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'


Same thing in OpenAPI 3.0, 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.


与恶龙缠斗过久,自身亦成为恶龙;凝视深渊过久,深渊将回以凝视…
Welcome to OStack Knowledge Sharing Community for programmer and developer-Open, Learning and Share
Click Here to Ask a Question

...