在 SwaggerHub 返回对象数组?
问题说明
我正在使用 OpenAPI 2.0 在 SwaggerHub 中定义 API 规范./contacts 请求返回一个联系人数组.定义如下:
I am defining an API specification in SwaggerHub using OpenAPI 2.0. The /contacts request returns an array of contacts. The definition is below:
/contacts:
get:
tags:
- contacts
summary: Get all the contacts
description: This displays all the contacts present for the user.
operationId: getContact
produces:
- application/json
- application/xml
responses:
200:
description: successful operation
schema:
$ref: '#/definitions/AllContacts'
400:
description: Invalid id supplied
404:
description: Contact not found
500:
description: Server error
definitions:
AllContacts:
type: array
items:
- $ref: '#/definitions/ContactModel1'
- $ref: '#/definitions/ContactModel2'
ContactModel1:
type: object
properties:
id:
type: integer
example: 1
firstName:
type: string
example: 'someValue'
lastName:
type: string
example: 'someValue'
ContactModel2:
type: object
properties:
id:
type: integer
example: 2
firstName:
type: string
example: 'someValue1'
lastName:
type: string
example: 'someValue1'
由于某种原因，它只返回第二个对象而不是整个对象数组.
For some reason, it only returns the second object not the whole array of objects.
我使用的是 OpenAPI 2.0，并且怀疑此版本不支持数组.
I am using OpenAPI 2.0 and suspect that the arrays are not well supported in this version.
正确答案
对象数组定义如下.items 的值必须是描述数组项的单个模型.
An array of objects is defined as follows. The value of items must be a single model that describes the array items.
definitions:
AllContacts:
type: array
items:
$ref: '#/definitions/ContactModel'
ContactModel:
type: object
properties:
id:
type: integer
example: 1
firstName:
type: string
example: Sherlock
lastName:
type: string
example: Holmes
默认情况下，Swagger UI 仅显示包含一项的数组示例，如下所示:
By default, Swagger UI displays the array examples with just one item, like so:
[
{
"id": 1,
"firstName": "Sherlock",
"lastName": "Holmes"
}
]
如果您希望数组示例包含多个项目，请在数组模型中指定多项目 example:
If you want the array example to include multiple items, specify the multi-item example in the array model:
definitions:
AllContacts:
type: array
items:
$ref: '#/definitions/ContactModel1'
example:
- id: 1
firstName: Sherlock
lastName: Holmes
- id: 2
firstName: John
lastName: Watson
这篇好文章是转载于：学新通技术网
