web-dev-qa-db-fra.com

Comment spécifier des exemples de paramètres GET dans Swagger?

J'utilise en ligne Swagger Editor pour créer une spécification Swagger pour mon API.

Mon API a un seul point de terminaison de demande GET, et j'utilise le code YAML suivant pour décrire les paramètres d'entrée:

paths:
  /fooBar:
    get:
      tags:
        - foobar
      summary: ''
      description: ''
      operationId: foobar
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - application/json
      parameters:
        - name: address
          in: query
          description: Address to be foobared
          required: true
          type: string
          example: 123, FakeStreet
        - name: city
          in: query
          description: City of the Address
          required: true
          type: string
          example: New York

Si je mets la balise example, j'obtiens une erreur disant:

n'est pas exactement l'un de <#/définitions/paramètre>, <#/définitions/jsonReference>

Comment définir un exemple lors de l'écriture des paramètres GET dans Swagger?

swaggerswagger-2.0swagger-editoropenapi
15
Devdatta Tengshe

OpenAPI 2.0

OpenAPI/Swagger 2.0 n'a pas le mot clé example pour les paramètres non-body. Vous pouvez spécifier des exemples dans le paramètre description. Certains outils comme Swagger UI v2, v3.12 + et Dredd prennent également en charge le x-example propriété d'extension à cet effet:

      parameters:
        - name: address
          in: query
          description: Address to be foobared. Example: `123, FakeStreet`.  # <-----
          required: true
          type: string
          x-example: 123, FakeStreet   # <-----

OpenAPI 3.0

Les exemples de paramètres sont pris en charge nativement dans OpenAPI 3.0:

      parameters:
        - name: address
          in: query
          description: Address to be foobared
          required: true
          schema:
            type: string
            example: 123, FakeStreet   # <----
          example: 456, AnotherStreet  # Overrides schema-level example
25
Helen