How to define different responses for same HTTP status code in OpenAPI (Swagger)?

23,546

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
Share:
23,546
Nomura Nori
Author by

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, 2022

Comments

  • Nomura Nori
    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
    iamjoshua about 4 years
    this 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
    Helen about 4 years
    @iamjoshua Currently Swagger UI does not generate examples for oneOf and anyOf models, but you can work around this by providing a custom example or examples - as in my answer. If there are issues with other renderer tools, consider filing bug reports with the tooling vendors.