I'm really struggling to understand the format of the examples section of a response. I have the following response defined for a 500 Internal Sever error.
500InternalServerError:
description: The server encountered an unexpected condition which prevented it from fulfilling the request
schema:
allOf:
- $ref: '#/definitions/Failure'
headers:
X-Rate-Limit-Limit:
description: The number of allowed requests in the current period
type: integer
X-Rate-Limit-Remaining:
description: The number of remaining requests in the current period
type: integer
X-Rate-Limit-Reset:
description: The number of seconds left in the current period
type: integer
examples:
application/json:
code: -1
message: The server encountered an unexpected condition which prevented it from fulfilling the request
When I load it up in swagger-ui, it looks like this:
How do I get the response to be formatted over multiple lines and look like this?:
{
"code": "-1",
"message": "The server encountered an unexpected condition which prevented it from fulfilling the request"
}
The lack of pretty print in the response-level examples seems to be a bug or missing functionality in Swagger UI 3.0.x. Feel free to submit an issue on GitHub.
The workaround is to use a schema-level example instead:
definitions:
Failure:
type: object
...
example:
code: "-1" # Quotes force the number to be treated as a string
message: The server encountered an unexpected condition which prevented it from fulfilling the request
By the way, you do not need allOf when using $ref alone (without combining it with other items):
schema:
$ref: '#/definitions/Failure'
Related
I defined my authentication in security and components/securitySchemes.
In the Swagger documentation about response, they provide this example:
paths:
/something:
get:
...
responses:
...
'401':
$ref: '#/components/responses/UnauthorizedError'
post:
...
responses:
...
'401':
$ref: '#/components/responses/UnauthorizedError'
...
components:
responses:
UnauthorizedError:
description: Authentication information is missing or invalid
headers:
WWW_Authenticate:
schema:
type: string
I have a lot more paths than two, and to access any of them, the client has to be authenticated. I would like to avoid the '401' definition for each path, and define it once globally, if it is possible somehow.
How is it possible to use this response for each path?
'401':
$ref: '#/components/responses/UnauthorizedError'
You can't, if you want the response to show up on that particular endpoint.
I avoid the repetition in favour of important errors by not adding them to each endpoint and instead putting the well understood standard responses - 401, 403, 429, 404, 503 - on either a status endpoint or on the root method. eg:
'/{foo}/{bar}/status':
get:
tags:
- api
responses:
'200':
description: successful response with a resource
content:
application/json:
schema:
$ref: '#/components/schemas/statusResponse'
'400':
$ref: '#/components/responses/400_error_response'
'401':
$ref: '#/components/responses/401_error_response'
'403':
$ref: '#/components/responses/403_error_response'
'404':
$ref: '#/components/responses/404_error_response'
'500':
$ref: '#/components/responses/500_error_response'
The boilerplate responses would then all refer to the standard responses.
Real endpoints then typically have a well defined response specific to that opearation and the things that may go specifically wrong.
'/{foo}/{bar}/segment':
post:
summary: checks username is found or not
description: |-
checks username and returns 204 if found else 403
operationId: checkUsername
tags:
- Login
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/segment_POST_request'
responses:
'200':
$ref: '#/components/responses/segment_POST_200_response'
'403':
$ref: '#/components/responses/403_forbidden_response'
'500':
$ref:
'#/components/responses/500_internal_server_error_replayable_response'
One thing I ensure is for error responses, the possible error codes for that operation are included in the response, like so:
500_internal_server_error_replayable_response:
description: |-
The following `500 Internal Server Error` errors can occur during the API processing.
| errorCode | cause | details |
| - | - | - |
| `SOME.ERROR.500` | There was an error processing the request either in Foo or on a downstream system | A request to something failed, Bar or Baz however the error is recoverable and can be replayed |
| `SOME.ERROR.014` | Baz returned a `404` during the migration operation, even though it has previously confirmed the member exists | This is a fatal error during the migration process and cannot be recovered. The request should not be replayed. |
headers:
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
status: '500'
errorCode: SOME.ERROR.500
errorDescription: The request could not be processed
errorSubCode: ''
furtherDetails: ''
docLink: ''
Use an extension to add them in automatically as part of your build script.
What you're looking to do is not part of the OpenAPI standard. Responses are not inherited from parent objects; they must be explicitly added to every endpoint. You can include a $ref for each response, but with a well-defined spec with lots of endpoints, you'll end up with a lot of duplication, and it's likely an endpoint might miss a response or two over time as additions and modifications are made. Plus, it's simply not a good authoring experience.
To prevent this problem, add an extension to your responses, like this:
responses:
x-default-responses: true
'418':
description: Additional responses go here
The above spec will be the one that you work from. When done, have a script scan your completed yaml file, and replace that line with your list of default responses. Use this modified spec as the next stage of your development process (whatever it is you're using your OpenAPI spec for, be it documentation, testing, or SDK generation).
While you could have your script add the responses without the extension property (after all, it is just YAML you're writing), I recommend you don't do this. The extension makes your intent clear, so other editors will understand additional responses are present. Additionally, it is likely that (either now or one day in the future) you will have endpoints that do not conform to your default responses, so you wouldn't want to accidentally add those.
I am creating a well-organized OAS3 swagger documentation on swaggerhub. For every endpoint i am writing all possible answers like 200, 201, 204, 400, 401, 403, 404, 500 etc. In addition all methods have default parameters like X-Language-Code etc.
I am in such a place that the responses, models, parameters I use now begin to repeat themselves in each file. After a little research i learnt that i can create a domain and remote absolute url references to them.
There is no error when i used the 'definition's remotely like this:
/example:
get:
#some other informations here
responses:
200:
description: 'example description'
content:
application/json:
schema:
$ref: 'https://remote.example/url/2.0#/definitions/ExampleResponse'
But, apparently you can not use $ref keyword right below responses or 400 etc.. keyword like this:
This one not getting error but not rendering the remote reference
responses:
400:
$ref: 'https://remote.example/url/2.0#/responses/Error400'
or this:
This one gives error
responses:
$ref: 'https://remote.example/url/2.0#/responses'
Even, i can not use 'parameters' as i expected:
/example:
get:
parameters:
- languageCode:
$ref: 'https://remote.example/url/2.0#/parameters/languageCode'
/example:
get:
parameters:
- $ref: 'https://remote.example/url/2.0#/parameters/'
I dont want to rewrite all reference definitions below every documentation.
I am confused about using and referencing 'domain's. Can someone explain or referencing a document about this situations since i couldn't found any documentation about it.
Update: OpenAPI 3.0 domains are now supported in SwaggerHub.
As of December 2018, SwaggerHub domains only support the OpenAPI 2.0 syntax but not OpenAPI 3.0. OpenAPI 3.0 and 2.0 use slightly different syntax for parameters, responses, etc., this means you cannot reference an OAS2 domain from an OAS3 API definition.
The workaround is to create another OpenAPI 3.0 API in SwaggerHub and use it as a "domain". You'll need to add a dummy header with openapi: 3.0.0, the info section and empty paths: {} to make the validator happy.
openapi: 3.0.0
info:
title: Common components
version: 1.0.0
paths: {}
# Put your common components here:
components:
schemas:
...
parameters:
...
responses:
...
Then you can reference components from this "domain" using the usual $ref syntax:
$ref: 'https://api.swaggerhub.com/apis/USERNAME/API-NAME/VERSION#/components/responses/Error400'
Make sure the hostname in $refs is API.swaggerhub.com (not APP.swaggerhub.com) and the link contains /apis/ (not /domains/).
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
Designing an API using editor.swagger.io I find myself unable to add a requestBody attribute, getting an error I cannot address:
Schema error at paths['/projects/{projectId}/user'].post
should NOT have additional properties
additionalProperty: requestBody
Jump to line 91
I don't understand what I'm doing wrong, especially after looking at the requestBody documentation. Research has brought me nothing other than the tendency for errors to be misleading.
EDIT: From what the answers here have shown, it looks like the editor is supposed to use OpenAPI 2.0, but actually expects 3.0 while returning errors for both. I'd use some help on what to use, given that I've included a
swagger: "2.0"
line at the beginning of the document.
While testing with openapi: 3.0.0 as shown by #Mike in his answer, I just get more errors about allowed additional properties.
Here's what's generating the error, line 91 being post: .
/projects/{projectId}/user:
post:
tags:
- projects
summary: Modify project user.
operationId: modifyProjectUser
parameters:
- name: projectId
in: path
description: ID of the project
required: true
type: integer
format: int32
requestBody:
content:
application/json:
schema:
$ref: '#/definitions/User'
responses:
"200":
description: Successful operation
schema:
type: array
items:
$ref: "#/definitions/User"
security:
- api_key: []
I got clarifications from an external source, so here's what I've learned:
Specifying swagger: 2.0 also means that the OpenAPI Specification 2.0.0 is expected by the editor, whereas I thought it used OAS 3.
I'm still unsure about why in: body did not work in the first place but I've added quotes around "body", which made the error disappear. Then I tried removing the quotes and it worked fine.
The editor doesn't seem very reliable when it comes to error reporting.
This error message looked familiar. Try inserting a schema: underneath your parameter's required: line, then indent the type: and format: lines.
Since I have not yet set up my own SwaggerUI server. I took your code snippet and pasted it into SwaggerHub. Then I removed the $ref: lines just to further simplify the codebase. Here's a screenshot of the error-free result.
In my case since I was using openapi: 3.0.0. The schema $ref should be '#/components/schemas/{schemaname}' instead of '#/definitions/schemas/{schemaname}'
I'm using http://editor.swagger.io to design an API and I get an error which I don't know how to address:
Schema error at paths['/employees/{employeeId}/roles'].get.parameters[0]
should NOT have additional properties
additionalProperty: type, format, name, in, description
Jump to line 24
I have other endpoints defined in a similar way, and don't get this error. I wondered if I had some issue with indentation or unclosed quotes, but that doesn't seem to be the case. Google also did not seem to provide any useful results.
swagger: "2.0"
info:
description: Initial draft of the API specification
version: '1.0'
title: App 4.0 API
host: api.com
basePath: /v1
tags:
- name: employees
description: Employee management
schemes:
- https
paths:
/employees/{employeeId}/roles:
get:
tags:
- employees
summary: "Get a specific employee's roles"
description: ''
operationId: findEmployeeRoles
produces:
- application/json
parameters:
- name: employeeId <====== Line 24
in: path
description: Id of employee whose roles we are fetching
type: integer
format: int64
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/Role'
'403':
description: No permission to see employee roles
'404':
description: EmployeeId not found
Any Hints?
The error message is misleading. The actual error is that your path parameter is missing required: true. Path parameters are always required, so remember to add required: true to them.
Had the same problem. I accidentally mixed up the syntax from Swagger 2.0 with Openapi 3.0.x. In Openapi 3.0.x, definitions are redefined as components. In the online editor you can click on the button Edit > Convert to OpenAPI 3 to use Openapi 3.0.x.
Read more about components here.
Remark:
OAS 3 is the latest version of the
OpenAPI Specification.
For me the cause of the error was a missing a leading slash in the path (internal/resource instead of /internal/resource).
And yes the error message is extremely unhelpful.
In my case I was missing parameter definition in api definition
- name: parameterName
in: query
description: parameter's description here.
required: false
schema:
type: string
In my case it had the wrong indentation for the example. It was:
content:
application/json:
schema:
$ref: '#/components/schemas/someresponse'
examples:
example1:
value:
param1: "some string"
param2: "123"
Rather than:
content:
application/json:
schema:
$ref: '#/components/schemas/someresponse'
examples:
example1:
value:
param1: "some string"
param2: "123"
But the VScode open api preview with swaggerUI didn't show any errors and everything looked valid.
The syntax requires might require two parameters, as mentioned by Helen required: true is need so is type:DataType . The error is misleading.