我正在使用 OpenAPI 3.0 和 SwaggerHub 设计一个 API。我的 API 有一个 GET 端点,它以 XML 格式返回员工数组:
<Employees>
<Employee>
<EmpId>001</EmpId>
<Name>Steven</Name>
<Mobile>1-541-754-3010</Mobile>
<EmailId>[email protected] /cdn-cgi/l/email-protection</EmailId>
</Employee>
<Employee>
<EmpId>002</EmpId>
<Name>Mark</Name>
<Mobile>1-551-754-3010</Mobile>
<EmailId>[email protected] /cdn-cgi/l/email-protection</EmailId>
</Employee>
</Employees>
这是到目前为止我的 OpenAPI YAML 文件:
openapi: 3.0.0
info:
title: General Document
version: "1.0"
contact:
email: [email protected] /cdn-cgi/l/email-protection
description: >
# Introduction
This document describes a list of API's available. \
paths:
/employees:
get:
description: This will return employees information in JSON and XML formats
responses:
200:
$ref: '#/components/responses/employeesAPI'
components:
responses:
employeesAPI:
description: This will return information about employees
content:
application/xml:
schema:
$ref: '#/components/schemas/EmployeesInfo'
schemas:
Employee:
type: object
required:
- EmpId
- Name
- Mobile
- EmailId
properties:
EmpId:
type: string
example: Employee id goes here
description: Employee id
Name:
type: string
example: Employee name goes here
description: Employee name
Mobile:
type: string
example: Employee mobile goes here
description: Employee mobile
EmailId:
type: string
example: Employee email goes here
description: Employee email
EmployeesInfo:
type: object
required:
- Employee
properties:
Employee:
$ref: '#/components/schemas/Employee'
xml:
name: EmployeesInfo
# Added by API Auto Mocking Plugin
servers:
- description: SwaggerHub API Auto Mocking
url: https://virtserver.swaggerhub.com/name2200/test/1.0
问题在于 SwaggerHub 中显示的 XML 响应示例与预期的响应 XML 不匹配。
如何正确定义 XML 对象数组?
按如下方式更改您的架构。EmployeesInfo
应该被定义为一个数组并且有xml.wrapped https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#user-content-xmlwrapped = true
。还要确保每个模式指定xml.name
以及相应的 XML 标记名称。
components:
...
schemas:
Employee:
type: object
...
xml:
name: Employee
EmployeesInfo:
type: array
items:
$ref: '#/components/schemas/Employee'
xml:
name: Employees
wrapped: true
Swagger UI 将显示响应示例,如下所示(此示例是从响应架构自动生成的):
<EmployeesInfo>
<Employee>
<EmpId>Employee id goes here</EmpId>
<Name>Employee name goes here</Name>
<Mobile>Employee mobile goes here</Mobile>
<EmailId>Employee email goes here</EmailId>
</Employee>
</EmployeesInfo>
如果您想显示自定义示例,例如包含 2 名员工的数组,添加自定义响应示例:
components:
responses:
employeesAPI:
description: This will return information about employees
content:
application/xml:
schema:
$ref: '#/components/schemas/EmployeesInfo'
# Custom example of response XML
example: |-
<Employees>
<Employee>
<EmpId>001</EmpId>
<Name>Steven</Name>
<Mobile>1-541-754-3010</Mobile>
<EmailId>[email protected] /cdn-cgi/l/email-protection</EmailId>
</Employee>
<Employee>
<EmpId>002</EmpId>
<Name>Mark</Name>
<Mobile>1-551-754-3010</Mobile>
<EmailId>[email protected] /cdn-cgi/l/email-protection</EmailId>
</Employee>
</Employees>
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系:hwhale#tublm.com(使用前将#替换为@)