How to define different responses for same HTTP status code in OpenAPI (Swagger)?
This is possible in OpenAPI 3.0 but not in 2.0.
OpenAPI 3.0 supports oneOf
for specifying alternate schemas for the response. You can also add multiple response examples
, such as successful and failed responses. Swagger UI supports multiple examples
since v. 3.23.0.
openapi: 3.0.0
...
paths:
/something:
get:
responses:
'200':
description: Result
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ApiResultOk'
- $ref: '#/components/schemas/ApiResultError'
examples:
success:
summary: Example of a successful response
value:
result: true
token: abcde12345
error:
summary: Example of an error response
value:
result: false
errorCode: "00002"
errorMsg: "duplicated account already exist"
components:
schemas:
ApiResultOk:
type: object
properties:
result:
type: boolean
enum: [true]
token:
type: string
required:
- result
- token
ApiResultError:
type: object
properties:
result:
type: boolean
enum: [false]
errorCode:
type: string
example: "00002"
errorMsg:
type: string
example: "duplicated account already exist"
In OpenAPI/Swagger 2.0, you can only use a single schema per response code, so the most you can do is define the varying fields as optional and document their usage in the model description
or operation description
.
swagger: "2.0"
...
definitions:
ApiResult:
type: object
properties:
result:
type: boolean
token:
type: string
errorCode:
type: string
errorMsg:
type: string
required:
- result
Nomura Nori
I believe we can inspire other people with our job. I am a highly experienced and skilled Mobile & Full-Stack Web Developer with a strong background knowledge in software development and I have the ability to work independently or as part of a team. Highly motivated to deliver exceptional quality with a strong love for detail and great usability. Self-organized with strong technical and communication skills. I enjoy taking an idea and going through the process of building wire-frames, database models, business objects, web services and finally a user-friendly Mobile and Web App that is not only easy to navigate, but extremely responsive.
Updated on July 09, 2022Comments
-
Nomura Nori over 1 year
I'm writing an OpenAPI spec for an existing API. This API returns status 200 for both success and failure, but with a different response structure.
For example, in the signup API, if the user signed up successfully, the API sends status 200 with the following JSON:
{ "result": true, "token": RANDOM_STRING }
And if there is a duplicated user, the API also sends status 200, but with the following JSON:
{ "result": false, "errorCode": "00002", // this code is duplicated error "errorMsg": "duplicated account already exist" }
In this case, how to define the response?
-
iamjoshua about 4 yearsthis is not being rendered properly in the swaggerhub and other swagger file renderers. It doesn't reference the Proper Schema in the specific response code it was declared. It just shows a blank response and not using the schema declared,
-
Helen about 4 years@iamjoshua Currently Swagger UI does not generate examples for
oneOf
andanyOf
models, but you can work around this by providing a customexample
orexamples
- as in my answer. If there are issues with other renderer tools, consider filing bug reports with the tooling vendors.