swagger - 如何在OpenAPI(Swagger)中为相同的HTTP状态代码定义不同的响应？

Question

我正在为现有API编写OpenAPI规范。该API会针对成功和失败返回状态200，但具有不同的响应结构。

例如，在注册API中，如果用户成功注册，则该API使用以下JSON发送状态200：

{
    "result": true,
    "token": RANDOM_STRING
}

并且如果存在重复的用户，API也会发送状态200，但带有以下JSON：

{
    "result": false,
    "errorCode": "00002", // this code is duplicated error
    "errorMsg": "duplicated account already exist"
}

在这种情况下，如何定义响应？

Answer 1

在OpenAPI 3.0中是可行的，但在2.0中则不可行。

OpenAPI 3.0支持oneOf为响应指定备用模式。您还可以添加多个响应examples，例如成功和失败的响应。从3.23.0版开始，Swagger UI支持多个examples。

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"

在OpenAPI / Swagger 2.0中，每个响应代码只能使用一个架构，因此，您最多只能将各种字段定义为可选字段，并在模型 description或操作 description中记录其用法。

swagger: "2.0"
...

definitions:
  ApiResult:
    type: object
    properties:
      result:
        type: boolean
      token:
        type: string
      errorCode:
        type: string
      errorMsg:
        type: string
    required:
      - result