问题
This question is a follow-up to this similar one - as @Helen requested a new question be asked.
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'
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
then it works fine.
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.
回答1:
Schemas do not support multiple examples
, they only support a single example
.
Multiple examples
can only be used in:
- 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
来源:https://stackoverflow.com/questions/62088926/swagger-editor-3-8-examples-not-working-for-reference-array-schema