Generating Swagger 2.0-Compliant Specification for a RESTful API

The CentraSite Business UI enables you to generate Swagger 2.0-compliant specification for the REST APIs that are available to you. The generated Swagger specification helps to integrate with other third-party providers who follow the Swagger 2.0 specifications.

Generation of a Swagger 2.0-compliant specification for REST APIs can be considered for the following scenarios:

Convert a RAML 0.8 specification of an existing REST API into the Swagger 2.0 specification.

Capture the latest information available on a REST API that was created with RAML 0.8 or Swagger 2.0 specification into the Swagger 2.0-compliant specification.

Create a Swagger 2.0-compliant specification for the new REST API created from scratch.

Generation of a Swagger 2.0-compliant specification for REST APIs is achieved in the following ways:

Execution of the Download Documents action for REST APIs: At any time, when you execute the Download Documents action for a particular REST API to have updated information on the REST API, CentraSite generates the Swagger 2.0-compliant specification with the updated information of that particular REST API.

Publishing/Republishing of REST APIs to API-Portal gateways: At any time, when you re-publish a particular REST API to an API-Portal gateway, CentraSite generates the Swagger 2.0-compliant specification with the updated information of that particular REST API.

To generate the Swagger 2.0-compliant specification for a REST API, you must have view permission on the particular REST API and all of the supporting documents that are associated with that REST API.

To generate a Swagger 2.0-compliant specification for a REST API or a set of REST APIs

1. In CentraSite Business UI, go to the page that contains the REST API or the set of REST APIs for that you want to generate the Swagger 2.0-compliant specification.

2. Display the details page of a REST API or select the check boxes of multiple REST APIs to generate the Swagger 2.0-compliant specification, and choose Download Documents from the actions bar.

3. The Download Documents dialog contains the Include all applicable supporting documents option, which allows you to include the associated documents (from the Supporting Document Library) in the archive file.

CentraSite appends the generated Swagger 2.0-compliant specification to the Documents attribute of the Specification profile in the REST API’s details page. This Swagger 2.0-compliant specification is prefixed by “Generated Swagger File:” and represented in the specific format: <Name of the REST API>.json

Note:

The generated Swagger 2.0-compliant specification will exhibit the CentraSite defined mappings. You can easily compare the generated Swagger 2.0-compliant specification with the standard Swagger 2.0 specification to find discrepancies. For a list of the supported Swagger mappings in REST APIs, refer to the section Swagger to CentraSite REST API Mappings.

The archive file is organized as a directory that holds a collection of downloaded files. If any of the names of the downloaded files are not unique; then such files are stored with consecutive numbers (for example, SwaggerA_1.json, SwaggerA_2.json, etc.).

When you generate a Swagger 2.0-compliant specification for a REST API, for example, Weather API, that was imported into CentraSite using a RAML specification, Weather.raml, and has an associated document in the Supporting Document Library, Weather Data.docx, the resulting .zip file expands into a folder with the following files:

If at a later stage, you generate a Swagger 2.0-compliant specification for the same REST API, for example, Weather API, which contains a Swagger 2.0-compliant specification in the zip file, CentraSite overwrites the existing Swagger 2.0-compliant specification.