如何在 OpenAPI 中定义对象的 XML 数组? [英] How to define an XML array of objects in OpenAPI?

问题描述

我正在使用 OpenAPI 3.0 和 SwaggerHub 设计 API.我的 API 有一个 GET 端点，它以 XML 格式返回一组员工:

I'm designing an API using OpenAPI 3.0 and SwaggerHub. My API has a GET endpoint that returns an array of employees in XML format:

<Employees>
  <Employee>
    <EmpId>001</EmpId>
    <Name>Steven</Name>
    <Mobile>1-541-754-3010</Mobile>
    <EmailId>[e-mail]</EmailId>
  </Employee>
  <Employee>
    <EmpId>002</EmpId>
    <Name>Mark</Name>
    <Mobile>1-551-754-3010</Mobile>
    <EmailId>[e-mail]</EmailId>
  </Employee>
</Employees>

这是我目前的 OpenAPI YAML 文件:

Here's my OpenAPI YAML file so far:

openapi: 3.0.0
info:
  title: General Document
  version: "1.0"
  contact:
    email: [e-mail]
  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 不匹配.

The problem is that the XML response example displayed in SwaggerHub does not match the expected response XML.

如何正确定义对象的 XML 数组?

How to properly define an XML array of objects?

推荐答案

按如下方式更改您的架构.EmployeesInfo 应定义为一个数组，并具有 xml.wrapped = true.还要确保每个架构都使用相应的 XML 标记名称指定 xml.name.

Change your schemas as follows. EmployeesInfo should be defined as an array and have xml.wrapped = true. Also make sure each schema specifies the xml.name with the corresponding XML tag name.

components:
  ...

  schemas:
    Employee:
      type: object
      ...
      xml:
        name: Employee

    EmployeesInfo:
      type: array
      items:
        $ref: '#/components/schemas/Employee'
      xml:
        name: Employees
        wrapped: true

Swagger UI 将显示如下响应示例(此示例是从响应架构自动生成的):

Swagger UI will display the response example as follows (this example is auto-generated from the response schema):

<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 个员工的数组，添加一个自定义响应示例:

If you want to display a custom example, e.g. an array with 2 employees, add a custom response example:

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>[e-mail]</EmailId>
              </Employee>
              <Employee>
                <EmpId>002</EmpId>
                <Name>Mark</Name>
                <Mobile>1-551-754-3010</Mobile>
                <EmailId>[e-mail]</EmailId>
              </Employee>
            </Employees>

这篇关于如何在 OpenAPI 中定义对象的 XML 数组?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！