Open API 2.0 Documentation

Last update: Download PDF Edit

1 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 the modeler or downloaded from /rest-doc/servicename/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.

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

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

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