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'
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.
Related
This question already has an answer here:
How not to copy-paste 3 generic error responses in almost all paths?
(1 answer)
Closed 8 months ago.
Currently I have something like this:
paths:
/home
...
responses:
200:
description: Successful operation
401:
$ref: '#/components/responses/401UnauthorizedDefault'
404:
$ref: '#/components/responses/404NotFound'
502:
$ref: '#/components/responses/502BadGatewayDefault'
/sign_up
...
responses:
201:
description: Created
401:
$ref: '#/components/responses/401UnauthorizedDefault'
404:
$ref: '#/components/responses/404NotFound'
502:
$ref: '#/components/responses/502BadGatewayDefault'
Is it possible to combine all three error responses and reference them with a $ref?
paths:
/home
...
responses:
200:
description: Successful operation
$ref: '#/components/responses/AllCommonErrorResponses’
/sign_up
...
responses:
201:
description: Created
$ref: '#/components/responses/AllCommonErrorResponses’
Currently I dont know all the error responses we will use. But there will be a set of shared. If we will extend them later, I dont want to go to every endpoint and adjust the responses.
OpenAPI v3 does not allow to reference a list of multiple responses.
You can use specific (e.g., "200") response codes or default for others.
There is no option to import a standard list of responses and reuse it.
If we follow the OAS3 spec for Response here we can see that each response status code can have multiple media types and each media type in turn has a schema particular to it.
UseCase : For example oas3 example below, we can see 200 has a binary stream response but 400 has 3 media-types:application/json, application/xml, text/plain.
So is the client expected to request accept-type header with all the media-types mentioned below. How can we have specific media-type for 400 response code, or basically how we can convey to the REST Service to respond with media type as application/xml when its a 400 bad request and if 200 is returning a binary stream.
Does this OAS3 response multiple media-type make sense for Client/Server Errors. If yes then whats the accept-type set for expecting, say "application/xml" for 400 bad request.
Please refer the below swagger UI snap. Where we see a drop-down for the media-types for error code as well. But when we try out executing the rest operations, the accept header is only populated as per the 200 status code's media-type
openapi: 3.0.0
info:
version: "1.0"
title: Resource
description: Resource service
paths:
/resource:
get:
summary: getResource
description: getResource
operationId: get-resource
responses:
"200":
description: a binary document to be returned
content:
application/octet-stream:
schema:
type: string
format: binary
"400":
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/Error400Element"
application/xml:
schema:
$ref: "#/components/schemas/Error400Element"
text/plain:
schema:
$ref: "#/components/schemas/Error400Element"
"500":
description: Internal Server Error
content:
application/json:
schema:
$ref: "#/components/schemas/Error500Element"
application/xml:
schema:
$ref: "#/components/schemas/Error500Element"
text/plain:
schema:
$ref: "#/components/schemas/Error500Element"
servers:
- url: http://localhost:8088/
components:
schemas:
Error400Element:
type: object
required:
- name
properties:
name:
type: string
number:
type: integer
Error500Element:
type: object
properties:
number:
type: integer
flag:
type: boolean
EDIT : modified the OAS3 spec and the SwaggerUI
My server application sends json response in the following format
{
result: ... //this could be success or error
additional-info: ... //this is a wrapper and could contains information depending the the operation
}
additional-info could be a success message (eg "operation successful"), error message (eg "operation failed") or say an object in string format (eg {user-name: manu}.
I have created swagger definition of the above object as follows:
ServerSuccessResponse:
type: object
properties:
result:
type: string
enum:
- success
additional-info:
type: string
enum:
- SuccessMessages
- UserResponse
required:
- result
- additional-info
ServerFailureResponse:
type: object
properties:
result:
type: string
enum:
- error
additional-info:
type: string
enum:
- FailureMessages
Then I am trying to use the above definition in APIs as follows
/user/username:
post:
tags:
- new user
summary: Add a new user to the database
description: Use this path to add a new user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewUser'
responses:
'200':
description: means the user was added successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ServerSuccessResponse'#BUT ITS NOT CLEAR WHAT ADDITIONAL-INFO CONTAINS
'404':
description: >-
Only a signed in user can add a question. This response means that
the user isn't signed in.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerFailureResponse' #BUT ITS NOT CLEAR WHAT ADDITIONAL-INFO CONTAINS
'500':
description: >-
means some internal error occur on the server while doing the
operation. The state of the operation if un-determined and the
operation could be successful, failed or partially successful
(because some database operations are not rolled back if error
occurs!
content:
application/json:
schema:
$ref: '#/components/schemas/ServerFailureResponse'#BUT ITS NOT CLEAR WHAT ADDITIONAL-INFO CONTAINS
My issue is that at the moment, ServerFailureResponse or ServerSuccessResponse doesn't tell what additional-info would contain. I would like to redesign the API definition such that what is contained in the additional-info also gets clear. Is there a way I could do it? In code, I still want to use additional-info as wrapper. I only want that in Swagger, the content of additional-info is clear for each response.
This is a simplified version of my OpenAPI 3.0 definition I'm viewing on the Swagger Editor online. I am trying to have the two responses for error codes 401 and 403, that share the same schema, show different examples - this doesn't seem to work and I still see the referenced type as example.
Can you help me figuring out what's wrong with the definitions?
openapi: 3.0.0
info:
version: '1.0'
title: A service
paths:
/doSomething:
post:
requestBody:
content:
application/json:
schema:
type: string
example: A string
responses:
401:
$ref: '#/components/responses/Unauthorized'
403:
$ref: '#/components/responses/Denied'
components:
responses:
Unauthorized:
description: The endpoint cannot be reached because the request is not authorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: unauthorized
Denied:
description: The request's authorizations don't match the required ones needed to access the resource
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: permissions denied
schemas:
Error:
type: object
properties:
error:
type: string
Your definition is correct, and the response example show up in Swagger Editor 3.6.5+ and Swagger UI 3.17.4+. Also, multiple examples are supported in Swagger UI 3.23.0+ and Editor 3.6.31+.
I am not sure whether this is at the heart of your problem but I noticed that the HTTP status codes in your path respone sections aren't given enclosed in quotation marks. The OpenAPI specification v3.x (in contrast to v2.x) makes this mandatory which you might want to look up here:
https://swagger.io/specification/#responses-object
https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#responses-object
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'
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.