Publish an OpenAPI (Swagger) document for your app's REST API in Jitterbit App Builder

Introduction

An OpenAPI (Swagger) document is a standardized, machine-readable description of a REST API, defined by the OpenAPI Specification. Since App Builder 4.67, you can publish an OpenAPI (Swagger) document describing your app's REST API, in JSON or YAML format. Any tool that supports OpenAPI, whether other applications of the Harmony platform (such as API Manager) or external, third-party tools, can retrieve this document without authentication to automatically discover your application's available endpoints, their parameters, and the authentication method each one requires. This page describes how to publish this document, where it's available, what it includes, and how authentication methods are mapped. At the end, there is a list of current known issues and limitations.

App Builder can also do the inverse operation; that is, consume an external OpenAPI document to create a REST endpoint. See Import an OpenAPI (Swagger) document to create an endpoint to learn more.

Publish an OpenAPI document

App Builder does not publish an OpenAPI document for your application's APIs by default. Before you can publish one, you must have already published the app as a REST API endpoint. To publish an OpenAPI document, follow these steps:

1. Go to IDE > REST APIs.

2. Locate the application for which you want to publish an OpenAPI document and click the chevron icon in its tile. The REST API page for that API opens.

   If you don't see your application listed, you haven't yet published it as a REST API endpoint.

3. In the Service panel, click Edit.

4. Check the Publish Documentation option. This tells App Builder to generate and publish the OpenAPI document.

5. Optionally, provide a Summary and a Description.

6. Click Save.

By default, App Builder will include all of the API's resources in the OpenAPI document, unless you select resources to exclude.

Exclude a resource from the API documentation

If you want to exclude an individual resource from the OpenAPI documentation that will be generated, this is also configured from the API's REST API page:

1. Go to IDE > REST APIs.

2. Locate the application for which you want to publish an OpenAPI document and click the chevron icon in its tile. The REST API page for that API opens.

   If you don't see your application listed, you haven't yet published it as a REST API endpoint.

3. In the Resources panel, locate the resource you want to exclude from the documentation and click its details icon. The REST Resource page for that resource opens.

4. In the Resource panel, click Edit.

5. Check the Exclude From Documentation option. Doing so omits that resource from the generated document, even when Publish Documentation is enabled for the REST API as a whole.

6. Click Save.

OpenAPI document details

This section describes the details of the OpenAPI document App Builder can publish for your application's REST APIs.

Document URL

Once published, the OpenAPI document is available at the same base URL as your app's REST API, with openapi.json or openapi.yaml appended:

.../rest/v1/{endpoint}/openapi.json
.../rest/v1/{endpoint}/openapi.yaml

Replace {endpoint} with the REST API endpoint configured for your application (for example, northwinds).

Document content

The generated OpenAPI document reflects the REST API exposed by the application:

• Each published resource, including any child nodes, becomes a path in the document.

• Business object columns and properties become fields in the corresponding components/schemas model, with their App Builder data types mapped to OpenAPI data types.

• Input parameters become OpenAPI path or query parameters.

• Only custom events selected for REST exposure are included, using their configured URL-friendly name.

Authentication mapping

The generated document declares a security scheme in components/securitySchemes for each authentication method configured on the application's endpoints:

Known issues and limitations

The generated document is subject to the same known issues and limitations as the underlying REST API.