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.
Related
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
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.
I am writing API documentation using OpenAPI 3.0. At the moment I have:
paths:
/script/update:
post:
tags:
- "Script"
summary: Update a script
operationId: updateScript
responses:
'200':
description: OK
"404":
description: Not Found
requestBody:
description: A script object in order to make the request
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
subsite_id:
type: string
script:
type: object
properties:
script:
$ref: '#/components/schemas/ScriptType'
type:
type: string
enum:
- custom
- interface
- freshbot
- feeder
- getter
- smcf
status:
$ref: '#/components/schemas/ScriptStatus'
comment:
type: string
format: string
reason:
type: string
format: string
To problem comes when I try to use to Swagger UI.
The only thing that appears is the following:
What I want is that the script object can be filled out field by field for each of the properties it has, like the subsite_id. What am I missing?
Swagger UI 3.x and 4.x do not have a form editor for JSON objects, so all JSON data needs to be entered in the JSON format: { "prop": value, ... }
Here's the corresponding feature request you can track:
https://github.com/swagger-api/swagger-ui/issues/2771
Here is the snippet of code:
/getappsettings:
get:
summary: Gets the collection of app settings.
responses:
200:
description: The successful get app settings response.
schema:
type: array
items:
$ref: '#/definitions/KeyValueType'
example:
- key: 'APP_SUPPORT_EMAIL_ADDRESS'
value: 'test#example.com'
- key: 'APP_SUPPORT_PHONE_NUMBER'
value: '08 9123 4567'
In the mocked API from SwaggerHub, it returns an empty array.
The problem I found was that it should be 'examples:' and up one level instead of 'example:' and also needed specify the content type - here is the working example below ...
Here is the snippet of code
/getappsettings:
get:
summary: Gets the collection of app settings.
responses:
200:
description: The successful get app settings response.
schema:
type: array
items:
$ref: '#/definitions/KeyValueType'
examples:
application/json:
- key: 'APP_SUPPORT_EMAIL_ADDRESS'
value: 'test#example.com'
- key: 'APP_SUPPORT_PHONE_NUMBER'
value: '08 9123 4567'
It was a bug in SwaggerHub's mock server, which is already fixed. Your definition now produces a mocked response containing the specified example array.
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.