Swagger Editor 3.8 示例不适用于参考数组架构 [英] Swagger Editor 3.8 examples not working for reference array schema
问题描述
这个问题是这个类似问题的后续问题 - 因为@Helen 要求提出一个新问题.
This question is a follow-up to this similar one - as @Helen requested a new question be asked.
似乎数组类型模式只接受example",而不接受examples".以下架构在 editor.swagger.io 站点上产生错误:
It seems an array type schema only accepts "example", not "examples". The following schema produces an error on the editor.swagger.io site:
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"属性,例如:
But if I replace the "examples" attribute with "example", e.g.:
owners_reference_list:
type: array
items:
$ref: '#/components/schemas/user_reference'
example:
- domain: example.com
username: jsmith
然后它工作正常.
引用的问题得到了回答,Swagger Editor 3.6.21 支持examples",@Helen 的评论说 editor.swagger.io 站点正在使用版本 3.8.3.
The referenced question is answered that "examples" is supported in Swagger Editor 3.6.21, and the comment by @Helen says that the editor.swagger.io site is using version 3.8.3.
推荐答案
Schemas 不支持多个 examples
,它们只支持单个 example
.
Schemas do not support multiple examples
, they only support a single example
.
多个examples
只能用于:
- 请求正文:
requestBody.content.
.examples - 响应:
responses.
.content.
.examples - 使用
content
关键字的参数:.content. .examples
- request bodies:
requestBody.content.<media-type>.examples
- responses:
responses.<code>.content.<media-type>.examples
- parameters that use the
content
keyword:<parameter>.content.<media-type>.examples
这篇关于Swagger Editor 3.8 示例不适用于参考数组架构的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!