web-dev-qa-db-de.com

Wie spezifiziere ich Beispiele für GET-Parameter in Swagger?

Ich benutze den Online Swagger Editor , um eine Swagger-Spezifikation für meine API zu erstellen.

Meine API hat einen einzelnen GET-Anforderungsendpunkt und ich benutze den folgenden YAML-Code, um die Eingabeparameter zu beschreiben:

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

Wenn ich den Tag example einfüge, wird folgende Fehlermeldung angezeigt:

ist nicht genau einer von <#/definitions/parameter>, <#/definitions/jsonReference>

Wie setze ich ein Beispiel beim Schreiben von GET-Parametern in Swagger?

swaggerswagger-2.0swagger-editoropenapi
15
Devdatta Tengshe

OpenAPI 2.0

OpenAPI/Swagger 2.0 verfügt nicht über das Schlüsselwort example für Nicht-Body-Parameter. Sie können Beispiele im Parameter description angeben. Einige Tools wie Swagger UI v2, v3.12 + und Dredd unterstützen auch die x-example Erweiterungseigenschaft für diesen Zweck:

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

OpenAPI 3.0

Parameterbeispiele werden in OpenAPI 3.0 nativ unterstützt:

      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