или операция

у спецификацию OpenAPI для существующего API. Этот API возвращает статус 200 для успеха и неудачи, но с другой структурой ответа.

Например, в API регистрации, если пользователь успешно зарегистрировался, API отправляет статус 200 со следующим JSON:

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

И если есть дублированный пользователь, API также отправляет статус 200, но со следующим JSON:

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

В этом случае, как определить ответ?

 Ayush Gupta23 нояб. 2017 г., 05:16
По какой-то конкретной причине вы не используете разные коды ответов для разных ответов?
 Helen14 дек. 2017 г., 21:20
 Web Developer23 нояб. 2017 г., 05:48
Я строю документ для уже существующих API. Я не могу редактировать API, потому что есть много API, и теперь приложение использует API.

Ответы на вопрос(1)

Решение Вопроса

OpenAPI 3.0 поддерживаетoneOf для указания альтернативных схем для ответа. Вы также можете добавить несколько ответовexamplesтакие, как успешные и неудачные ответы (однако, несколькоexamples в настоящее времяне отображается в Swagger UI).

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

Ваш ответ на вопрос