How to specify examples for GET parameters in Swagger?
OpenAPI 2.0
OpenAPI/Swagger 2.0 does not have the example
keyword for non-body parameters. You can specify examples in the parameter description
. Some tools like Swagger UI v2, v3.12+ and Dredd also support the x-example
extension property for this purpose:
parameters:
- name: address
in: query
description: Address to be foobared. Example: `123, FakeStreet`. # <-----
required: true
type: string
x-example: 123, FakeStreet # <-----
OpenAPI 3.0
Parameter examples are supported natively in 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
Devdatta Tengshe
A GIS professional; Having moved on to a techno-managerial role, I hardly get the opportunity to get my hands dirty with code.
Updated on June 14, 2020Comments
-
Devdatta Tengshe almost 4 years
I'm using the online Swagger Editor to create a Swagger spec for my API.
My API has a single GET request endpoint, and I'm using the following YAML code to describe the input parameters:
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
If I put in the
example
tag, I get an error saying:is not exactly one from <#/definitions/parameter>,<#/definitions/jsonReference>
How do I set an example when writing GET parameters in Swagger?