web-dev-qa-db-fra.com

Comment définir différentes réponses pour le même code de statut HTTP dans OpenAPI (Swagger)?

J'écris une spécification OpenAPI pour une API existante. Cette API renvoie le statut 200 pour le succès et l'échec, mais avec une structure de réponse différente.

Par exemple, dans l'API d'inscription, si l'utilisateur s'est inscrit avec succès, l'API envoie le statut 200 avec le JSON suivant:

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

Et s'il y a un utilisateur dupliqué, l'API envoie également le statut 200, mais avec le JSON suivant:

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

Dans ce cas, comment définir la réponse?

swaggeropenapi
9
Nomura Nori

Cela est possible dans OpenAPI 3.0 mais pas dans 2.0.

OpenAPI 3.0 prend en charge oneOf pour spécifier des schémas alternatifs pour la réponse. Vous pouvez également ajouter plusieurs réponses examples, telles que les réponses réussies et ayant échoué. L'interface utilisateur de Swagger prend en charge plusieurs examples depuis la version 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"

Dans OpenAPI/Swagger 2.0, vous ne pouvez utiliser qu'un seul schéma par code de réponse, donc tout ce que vous pouvez faire est de définir les différents champs comme facultatifs et de documenter leur utilisation dans le modèle description ou l'opération 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

Si vos réponses se trouvent être de type array ou ont une structure commune et diffèrent dans un nœud sous un nœud de type array, il est possible de le faire même dans swagger 2.0. C'est à dire. cela fonctionnerait pour ceux-ci:

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

ou

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

et pareil. Définissez simplement la structure commune et utilisez enum dans la définition du tableau comme ceci:

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