如何在 Swagger 中指定 GET 参数的示例?
How to specify examples for GET parameters in Swagger?
我正在使用在线 Swagger Editor 为我的 API 创建 Swagger 规范。
我的 API 有一个 GET 请求端点,我使用以下 YAML 代码来描述输入参数:
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
如果我放入 example
标签,我会收到一条错误消息:
is not exactly one from <#/definitions/parameter>,<#/definitions/jsonReference>
Swagger写GET参数时如何设置示例?
OpenAPI 2.0
OpenAPI/Swagger 2.0 没有非正文参数的 example
关键字。您可以在参数 description
中指定示例。为此目的,Swagger UI v2、v3.12+ 和 Dredd 等一些工具也支持 x-example
扩展 属性:
parameters:
- name: address
in: query
description: Address to be foobared. Example: `123, FakeStreet`. # <-----
required: true
type: string
x-example: 123, FakeStreet # <-----
OpenAPI 3.0
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
我正在使用在线 Swagger Editor 为我的 API 创建 Swagger 规范。
我的 API 有一个 GET 请求端点,我使用以下 YAML 代码来描述输入参数:
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
如果我放入 example
标签,我会收到一条错误消息:
is not exactly one from <#/definitions/parameter>,<#/definitions/jsonReference>
Swagger写GET参数时如何设置示例?
OpenAPI 2.0
OpenAPI/Swagger 2.0 没有非正文参数的 example
关键字。您可以在参数 description
中指定示例。为此目的,Swagger UI v2、v3.12+ 和 Dredd 等一些工具也支持 x-example
扩展 属性:
parameters:
- name: address
in: query
description: Address to be foobared. Example: `123, FakeStreet`. # <-----
required: true
type: string
x-example: 123, FakeStreet # <-----
OpenAPI 3.0
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