Generating Swagger 2.0-Compliant File for a RESTful API

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

Generation of a Swagger 2.0-compliant file 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 file.

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

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

Generation of a Swagger 2.0-compliant file 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 file 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 file with the updated information of that particular REST API.

Execution of the predefined “Generate Swagger 2.0 File” policy action: CentraSite’s policy framework enables you to create policies that trigger an automated generation of the Swagger v2.0-compliant file when certain events occur on the REST APIs and its variants. For example, you might create a policy will automatically generate the Swagger v2.0-compliant file for a REST API or Virtual REST API after it is switched to a productive state.

Note:

CentraSite does not provide a Generate Swagger v2.0 File policy out-of-the-box. You must create this policy for your instance of CentraSite.

To generate Swagger v2.0-compliant file for a REST API, create a Generate Swagger v2.0 File policy that contains the CentraSite's built-in Generate Swagger 2.0 File action and apply this policy on the following events during which you want CentraSite to automatically generate the Swagger v2.0-compliant file for the REST APIs and Virtual REST APIs:

For more information about creating the Generate Swagger v2.0 File policy, see the CentraSite User’s Guide.

For a description of the action Generate Swagger 2.0 File, see the CentraSite Developer’s Guide.

To generate the Swagger 2.0-compliant file 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.

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

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 file, 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 file to the Documents attribute of the Specification profile in the REST API’s details page. This Swagger 2.0-compliant file 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 file will exhibit the CentraSite defined mappings. You can easily compare the generated Swagger 2.0-compliant file 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 file 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 file for the same REST API, for example, Weather API, which contains a Swagger 2.0-compliant file in the zip file, CentraSite overwrites the existing Swagger 2.0-compliant file.