OpenAPI 2.0 Documentation
Introduction
Every published REST service is automatically documented. The system generates a swagger.json file that conforms to the OpenAPI 2.0 specification (formerly known as the “swagger specification”). This file can be saved from Studio Pro or downloaded from /rest-doc/{location}/swagger.json.
If you need to communicate with the service from another app, you can use the swagger.json file to generate an API in many different systems, including Microsoft Visual Studio, React, Angular, and Java. This makes it easy to communicate between your different apps.
Many of the popular API tools support OpenAPI 2.0, including SoapUI, Postman, and Swagger UI (for a longer list of supported tools, see swagger.io/commercial-tools). This means that you can easily test your published service from any of these tools.
A technical description is presented below of which parts of the swagger.json file are generated.
Schema
The main schema object documents the service.
| Property | Generated Value |
|---|---|
swagger |
2.0 |
info.title |
The name of the service. |
info.description |
The public documentation of the service. |
info.version |
1.0.0 |
host |
The host on which the app is running. |
basePath |
/rest/servicename |
schemes |
The schemes of the server on which the app is running (http and/or https). |
responses |
Contains the unauthorized response when security is enabled. |
securityDefinitions |
Contains the basic authentication when security is enabled. |
security |
Contains the basic authentication when security is enabled. |
tags |
Each resource generates a tag with the name and description (public documentation) of the resource. |
paths |
Each group of operations generates a path object. See below for more information. |
Paths
The service’s operations are grouped by operation path. Each of these groups generates a PathItem with the operation path as the name. The PathItem has an Operation property for each operation in the group.
Operations
Each operation generates an Operation object:
| Property | Generated value |
|---|---|
tags |
The name of the resource. |
summary |
The public documentation summary of the operation. |
description |
The public documentation description of the operation. |
parameters |
The path and query parameters. For the POST, PUT, PATCH, and OPTIONS methods, there is also a body parameter. |
responses |
The OK response. If security is enabled, this is also the unauthorized response. |
deprecated |
Set to true when the operation is marked as deprecated. |