如何 return SwaggerHub 中的对象数组?
How to return an array of objects in SwaggerHub?
我正在使用 OpenAPI 2.0 在 SwaggerHub 中定义一个 API 规范。 /contacts
请求 returns 一组联系人。定义如下:
/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'
出于某种原因,它只是 returns 第二个对象而不是整个对象数组。
我正在使用 OpenAPI 2.0,我怀疑这个版本对数组的支持不佳。
对象数组定义如下。 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 显示仅包含一项的数组示例,如下所示:
[
{
"id": 1,
"firstName": "Sherlock",
"lastName": "Holmes"
}
]
如果您希望数组示例包含多项,请在数组模型中指定多项example
:
definitions:
AllContacts:
type: array
items:
$ref: '#/definitions/ContactModel1'
example:
- id: 1
firstName: Sherlock
lastName: Holmes
- id: 2
firstName: John
lastName: Watson
我意识到这有点离题,但我来到这里是为了寻找 OpenApi 3.0 的示例。对于寻找同样东西的其他人,这是如何做到的:
paths:
/product-category:
get:
summary: 'Returns all product categories'
operationId: readProductCategory
tags:
- productCategory
responses:
'200':
description: 'Details about all product categories'
content:
application/json:
schema:
type: array
items:
allOf:
- $ref: '#/components/schemas/Identifier'
- $ref: '#/components/schemas/ProductCategory'
我正在使用 OpenAPI 2.0 在 SwaggerHub 中定义一个 API 规范。 /contacts
请求 returns 一组联系人。定义如下:
/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'
出于某种原因,它只是 returns 第二个对象而不是整个对象数组。
我正在使用 OpenAPI 2.0,我怀疑这个版本对数组的支持不佳。
对象数组定义如下。 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 显示仅包含一项的数组示例,如下所示:
[
{
"id": 1,
"firstName": "Sherlock",
"lastName": "Holmes"
}
]
如果您希望数组示例包含多项,请在数组模型中指定多项example
:
definitions:
AllContacts:
type: array
items:
$ref: '#/definitions/ContactModel1'
example:
- id: 1
firstName: Sherlock
lastName: Holmes
- id: 2
firstName: John
lastName: Watson
我意识到这有点离题,但我来到这里是为了寻找 OpenApi 3.0 的示例。对于寻找同样东西的其他人,这是如何做到的:
paths:
/product-category:
get:
summary: 'Returns all product categories'
operationId: readProductCategory
tags:
- productCategory
responses:
'200':
description: 'Details about all product categories'
content:
application/json:
schema:
type: array
items:
allOf:
- $ref: '#/components/schemas/Identifier'
- $ref: '#/components/schemas/ProductCategory'