web-dev-qa-db-ja.com

OpenAPI（Swagger）で同じHTTPステータスコードに対して異なる応答を定義する方法は？

既存の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"
}

この場合、どのように応答を定義しますか？

swaggeropenapi
9
Nomura Nori

これはOpenAPI 3.0では可能ですが、2.0ではできません。

OpenAPI 3.0は、応答の代替スキーマを指定するためのoneOfをサポートしています。成功した応答と失敗した応答など、複数の応答examplesを追加することもできます。 Swagger UIは、v。3.23.0以降、複数の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では、応答コードごとに1つのスキーマしか使用できないため、さまざまなフィールドをオプションとして定義し、それらの使用法をモデルdescriptionまたは操作descriptionで文書化することができます。

_swagger: "2.0"
...

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

応答がarray型であるか、共通の構造を持ち、array型のノードの下にあるノードで異なる場合、swagger 2.0でも可能です。つまり。それはこれらのために働くでしょう：

[                                                                               
    {                                                                              
        "anything": 1                                                              
    },                                                                             
    {                                                                              
        "anything other": 2                                                        
    }                                                                              
]

または

{
  "errors": [
    {
      "code": "ERR_NO_CONTRACT",
      "error_message": "No contract found",
      "parameters": [],
      "placeholders": []
    }
  ]
}

同様に。次のように、共通の構造を定義し、配列定義でenumを使用するだけです。

swagger: '2.0'
info:
  version: v1
  title: title
definitions:
  MultiError400:
    type: array
    required:
      - errors
    items:
      type: object
      enum:
      - $ref: '#/definitions/FirstError'
      - $ref: '#/definitions/SecondError'
  FirstError:
    type: object
    required:
      - code
    properties:
      code:
        type: string
  SecondError:
    type: object
    required:
      - code
    properties:
      code:
        type: string
paths:
  /path:
    parameters:
      - name: name
        description: blah blah
        in: query
        required: true
        type: string
    post:
      consumes:
        - application/json
      responses:
        '400':
          description: Multiple 400 errors
          schema:
            $ref: '#/definitions/MultiError400'
0
helvete