Swagger Editor 3.8 示例不适用于引用数组架构
Swagger Editor 3.8 examples not working for reference array schema
此问题是 this similar one 的后续问题 - 因为 @Helen 要求提出一个新问题。
似乎数组类型模式只接受 "example",而不接受 "examples"。以下架构在 editor.swagger.io 站点上产生错误:
info:
title: Example Inc. REST API version 1.0
version: '1.0'
openapi: 3.0.0
components:
schemas:
user_reference:
properties:
comment:
type: string
middle_name:
type: string
domain:
pattern: '^[0-9A-Za-z][0-9A-Za-z.-]*$'
type: string
id:
minimum: 1
type: integer
first_name:
type: string
last_name:
type: string
username:
pattern: '^[0-9A-Za-z_.@-]+$'
type: string
type: object
owners_reference_list:
type: array
items:
$ref: '#/components/schemas/user_reference'
examples:
by_site:
summary: Access by site and username
value:
- domain: example.com
username: jsmith
by_id:
value:
- id: 14
summary: Access by id
by_other:
summary: Access by other attributes
value:
- middle_name: X.
last_name: Smith
comments: Standard user
first_name: John
responses:
ok:
content:
application/json:
schema:
type: string
description: |
...
paths:
/users:
description: |
A user account ...
get:
parameters:
- description: |
...
content:
application/json:
schema:
$ref: '#/components/schemas/owners_reference_list'
name: owners_ref
required: false
in: query
responses:
'200':
$ref: '#/components/responses/ok'
但是如果我用 "example" 替换 "examples" 属性,例如:
owners_reference_list:
type: array
items:
$ref: '#/components/schemas/user_reference'
example:
- domain: example.com
username: jsmith
然后它工作正常。
参考问题已回答 "examples" 在 Swagger Editor 3.6.21 中受支持,@Helen 的评论说 editor.swagger.io 站点正在使用版本 3.8.3。
Schemas 不支持多个 examples
,它们只支持一个 example
。
多个examples
只能用于:
- 请求正文:
requestBody.content.<media-type>.examples
- 回复:
responses.<code>.content.<media-type>.examples
- 使用
content
关键字的参数:<parameter>.content.<media-type>.examples
此问题是 this similar one 的后续问题 - 因为 @Helen 要求提出一个新问题。
似乎数组类型模式只接受 "example",而不接受 "examples"。以下架构在 editor.swagger.io 站点上产生错误:
info:
title: Example Inc. REST API version 1.0
version: '1.0'
openapi: 3.0.0
components:
schemas:
user_reference:
properties:
comment:
type: string
middle_name:
type: string
domain:
pattern: '^[0-9A-Za-z][0-9A-Za-z.-]*$'
type: string
id:
minimum: 1
type: integer
first_name:
type: string
last_name:
type: string
username:
pattern: '^[0-9A-Za-z_.@-]+$'
type: string
type: object
owners_reference_list:
type: array
items:
$ref: '#/components/schemas/user_reference'
examples:
by_site:
summary: Access by site and username
value:
- domain: example.com
username: jsmith
by_id:
value:
- id: 14
summary: Access by id
by_other:
summary: Access by other attributes
value:
- middle_name: X.
last_name: Smith
comments: Standard user
first_name: John
responses:
ok:
content:
application/json:
schema:
type: string
description: |
...
paths:
/users:
description: |
A user account ...
get:
parameters:
- description: |
...
content:
application/json:
schema:
$ref: '#/components/schemas/owners_reference_list'
name: owners_ref
required: false
in: query
responses:
'200':
$ref: '#/components/responses/ok'
但是如果我用 "example" 替换 "examples" 属性,例如:
owners_reference_list:
type: array
items:
$ref: '#/components/schemas/user_reference'
example:
- domain: example.com
username: jsmith
然后它工作正常。
参考问题已回答 "examples" 在 Swagger Editor 3.6.21 中受支持,@Helen 的评论说 editor.swagger.io 站点正在使用版本 3.8.3。
Schemas 不支持多个 examples
,它们只支持一个 example
。
多个examples
只能用于:
- 请求正文:
requestBody.content.<media-type>.examples
- 回复:
responses.<code>.content.<media-type>.examples
- 使用
content
关键字的参数:<parameter>.content.<media-type>.examples