Generating Swagger 2.0 and Open API-Compliant File for a REST Service
CentraSite Business UI enables you to generate Swagger 2.0 and Open API-compliant file for Open API REST Services. The generated OpenAPI file helps to integrate CentraSite with other third-party providers following the Swagger 2.0 and Open API specifications.
You would generate a Swagger 2.0 and Open API-compliant file for a REST Service to:
convert a RAML 0.8 specification of a REST Service into a Swagger 2.0 and Open API file.
capture complete and up-to-date information of a REST Service that was created with a RAML 0.8, Swagger 2.0 specification or Open API specification into a Swagger 2.0 and Open API-compliant file.
create a Swagger 2.0 and Open API-compliant file for a REST Service just created from scratch.
You can generate a Swagger 2.0 and Open API-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 and Open API-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 and Open API-compliant file with the complete and up-to-date information of the REST Service.
Execution of predefined API Specification Generator policy: Whenever you modify the information of a REST Service,
CentraSite triggers the predefined API Specification Generator policy and generates the Swagger 2.0 and Open API-compliant file with the complete, up-to-date information of the REST Service.
The API Specification Generator policy containing the built-in Generate API Specification policy action initiates the generation of Open API-compliant file, while it is in the Productive state. By default, the API Specification 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 and Open API-compliant file to be valid and referenced correctly, the following preconditions must 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 and Open API-compliant file. If the HTTP request or response message includes an XML schema definition, then
CentraSite ignores the XSD.
When migrating to 10.7, inline Schemas are converted as Component Schemas and referred from Requests or Responses. Inline schemas with same case sensitive content is converted to a single schema.
To generate Swagger 2.0 and Open API-compliant file for REST Service
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.
Click the
Search icon that is located next to the
Scope list.
2. In the Additional Search Criteria list, select Asset Types. Do one of the following:
1. 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. |
2. In the Choose Asset Types dialog box, select the Assets option button.
a. Click the chevron to expand the list of asset types.
b. Select one or more asset types, and then click OK.
3. Click the chevron to expand the list of asset types that are available to you.
4. Select REST Service.
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 and Open API-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.
4. Click Download Documents.
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.
5. Click Download.
This initiates the creation of an archive file. Once the archive file is created, CentraSite appends the generated Swagger 2.0 and Open API-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 API Specification 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 .
Example: Generated Swagger File: Weather Service.json
The Open API-compliant file is prefixed with Open API and represented in a specific format: OpenAPI-<Name of the REST Service>.json .
Example: OpenAPI-Weather Service.json
Note:
The generated Swagger 2.0 and Open API-compliant file exhibits the Swagger 2.0 and Open API mappings defined for the REST Service in CentraSite. You can easily compare the generated Swagger 2.0 and Open API-compliant file with the standard Swagger 2.0 and Open API specification and see if there is any discrepancy.
Structure of the Archive File
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, OpenAPIA_1.json, OpenAPIA_2.json, and so on.).
When you generate a Open API-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:
Weather.raml Weather Service.json Weather Data.docx OpenAPI-Weather Service.json In a later stage, when you generate the Open API-compliant file for the same Weather Service, which already contains a Open API-compliant file in the archive file, CentraSite overwrites the existing Open API-compliant file.