OpenAPI 3.0 Documentation

Last modified: August 20, 2024

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.