Generating Swagger 2.0-Compliant File for a REST Service

CentraSite Business UI enables you to generate Swagger 2.0-compliant file for Swagger REST Services. The generated Swagger file helps to integrate CentraSite with other third-party providers following the Swagger 2.0 specifications.

convert a RAML 0.8 specification of a REST Service into a Swagger 2.0 file.

capture complete and up-to-date information of a REST Service that was created with a RAML 0.8 or Swagger 2.0 specification into a Swagger 2.0-compliant file.

create a Swagger 2.0-compliant file for a REST Service just created from scratch.

You can generate a Swagger 2.0-compliant file for the REST Service in the following ways:

Using the Download Documents action: When you execute the Download Documents action for a REST Service in order to have an up-to-date information of the REST Service, CentraSite generates the Swagger 2.0-compliant file with the full and up-to-date information of the REST Service.

By Publishing/Republishing REST Service to API Portal gateways: When you re-publish a REST Service to an API Portal gateway, CentraSite generates the Swagger 2.0-compliant file with the complete and up-to-date information of the REST Service.

Execution of predefined Swagger Generator policy: Whenever you modify the information of a REST Service, CentraSite triggers the predefined Swagger Generator policy and generates the Swagger 2.0-compliant file with the complete and up-to-date information of the REST Service.

The Swagger Generator policy containing the built-in Generate Swagger 2.0 File policy action initiates the generation of Swagger v2.0-compliant file, while it is in the Productive state. By default, the Swagger Generator policy is installed in the New (inactive) state. To activate the policy, you must change the policy's lifecycle state to the Productive (active) state.

In order for the generated Swagger 2.0-compliant file to be valid and referenced correctly, the following preconditions must all be met:

Name of a HTTP method must be unique within the REST Service. If a name is not provided for the HTTP method, CentraSite uses the HTTP method in combination with the resource path.

The HTTP request and response messages with a valid JSON schema definition is only mapped properly in the Swagger 2.0-compliant file. If the HTTP request or response message includes an XML schema definition, then CentraSite ignores the XSD.

If one or more schemas are referred by another schema in the input specification file, then such referenced schemas are mapped as inline schemas to each HTTP method. The resulting schema definition in the generated Swagger 2.0-compliant file does not contain any reference from one schema to the other.

1. In CentraSite Business UI, access the Advanced Search panel in one of the following ways:

Click the Browse link that is located in the upper-left corner of the menu bar.

2. In the Additional Search Criteria list, select Asset Types. Do one of the following:

i. To search for the assets of type, REST Service, click Choose. This opens the Choose Asset Types dialog box.

A list of scopes that are available to you is displayed. By default, CentraSite contains the following predefined scopes:

Scope	Description
Everything	Displays a list of the currently available assets, organizations, and users in CentraSite registry.
Assets	Displays a list of the currently available assets in CentraSite registry. This is the default scope.

ii. In the Choose Asset Types dialog box, select the Assets option button.

iii. Click the chevron to expand the list of asset types that are available to you.

A list of currently defined REST Service assets is displayed in the Search Results page.

3. Click the REST Service you want to generate the Swagger 2.0-compliant file.

The REST Service details page is displayed. Also, the Actions bar displays a set of actions that are available for working with the displayed Service.

The Download Documents dialog box 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. By default, the supporting documents are included in the archive file.

This initiates the creation of an archive file. Once the archive file is created, CentraSite appends the generated Swagger 2.0-compliant file to the Documents attribute in the Specification profile. The Specification profile will be enabled in the details page of a REST API, only if the Swagger Generator policy is in the Productive state.

The Swagger 2.0-compliant file is prefixed with Generated Swagger File: and represented in a specific format: <Name of the REST Service>.json .

Note: The generated Swagger 2.0-compliant file exhibits the Swagger mappings defined for the REST Service in CentraSite. You can easily compare the generated Swagger 2.0-compliant file with the standard Swagger 2.0 specification and see if there is any discrepancy.

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, and so on.).

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

In a later stage, when you generate the Swagger 2.0-compliant file for the same Weather Service, which already contains a Swagger 2.0-compliant file in the archive file, CentraSite overwrites the existing Swagger 2.0-compliant file.