How to define an XML array of objects in OpenAPI? - swagger

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>steven#yourcomany.com</EmailId>
</Employee>
<Employee>
<EmpId>002</EmpId>
<Name>Mark</Name>
<Mobile>1-551-754-3010</Mobile>
<EmailId>mark#yourcomany.com</EmailId>
</Employee>
</Employees>
Here's my OpenAPI YAML file so far:
openapi: 3.0.0
info:
title: General Document
version: "1.0"
contact:
email: developer#email.com
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?

Answer 1

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>steven#yourcomany.com</EmailId>
</Employee>
<Employee>
<EmpId>002</EmpId>
<Name>Mark</Name>
<Mobile>1-551-754-3010</Mobile>
<EmailId>mark#yourcomany.com</EmailId>
</Employee>
</Employees>