OpenAPI 3.0 Documentation
Introduction
Every published REST service is automatically documented. The system generates a openapi.json file that conforms to the OpenAPI 3.0 specification. This file can be saved from Studio Pro or downloaded from /rest-doc/{location}/openapi.json, where {location} is the location of the REST service, for instance rest/myservice/v1.
If you need to communicate with the service from another app, you can use the openapi.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 3.0, including Postman and Swagger UI (for a longer list of supported tools, see tools.openapis.org). 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 openapi.json file are generated.
Schema
The main schema object documents the service.
| Property | Generated Value |
|---|---|
openapi | 3.0 |
info.title | The name of the service. |
info.description | The public documentation of the service. |
info.version | 1.0.0 |
servers | Contains the baseURL on which the app is running. |
paths | Each group of operations generates a path object. See below for more information. |
components.schemas | Contains reusable schemas for the entities that are used in the requests or responses. |
components.responses | Contains the unauthorized response when security is enabled. |
components.securitySchemes | 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
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. |
requestBody | Contains the type and schema information for form and body parameters for POST, PUT, and PATCH methods. |
parameters | The path, query, and header parameters and their location and type information. |
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. |