How to define an XML array of objects in OpenAPI?

Question

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

Here's my OpenAPI YAML file so far:

openapi: 3.0.0
info:
  title: General Document
  version: "1.0"
  contact:
    email: [email protected]
  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

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

How to properly define an XML array of objects?

Helen · Accepted Answer · 2019-09-24 11:19:33Z

3

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 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>

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

edited Sep 24, 2019 at 11:19

answered Sep 24, 2019 at 11:02

Helen

99.8k17 gold badges280 silver badges352 bronze badges

Sign up to request clarification or add additional context in comments.

3 Comments

payne Over a year ago

Is there an OpenAPI annotation to do this with my model in Java ?

Helen Over a year ago

@payne I don't know. Please ask a new question.

payne Over a year ago

I created this question, for now: stackoverflow.com/q/65797677/9768291

Collectives™ on Stack Overflow

How to define an XML array of objects in OpenAPI?

1 Answer 1

3 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

3 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related