Service Version Metadata

Export metadata in Swagger documents

Any REST service version registered in the Sentinet Repository can be exported in the external Swagger metadata document. This feature is similar to Sentinet producing WSDL documents for SOAP services (described in the Service Version Metadata for SOAP services), and it is available independent of how the service version was registered in the first place, manually or from the existing Swagger document.

Note

Swagger document produced for a REST service version is not the same as a Sentinet Export Package created for the same service version, and they typically serve different purposes. Swagger document is just a short description of the REST API in the industry standard JSON or YAML formats, while Sentinet Export Package is an all-inclusive description and configuration of the REST API in the Sentinet private format.

Click OPENAPI toolbar button and select Json or Yaml menu options to select the format of the Swagger or OpenAPI v3 metadata document to retrieve from the Sentinet console.

Figure. Swagger metadata menu options.

If the browser supports application/json Content-Type or text/yaml then the Swagger document will be shown in the browser, otherwise the browser may suggest saving the document as an external file.

Note

The Swagger URL that shows up in the browser can be used as a source URL for other programs and utilities that can work with Swagger documents. Just like a WSDL URL produced by Sentinet, a Swagger URL by default is secured and is valid for the default period of 20 minutes.

Figure. Swagger document and Swagger URL in the browser.

View metadata in external Swagger Viewer

Sentinet provides integrations with third-party Swagger viewers that have the capability to display REST API's documentation from the URL of the external Swagger document. For example, Swagger.IO offers Swagger UI, a tool which is available both as a free stand-alone download and as a free online demo viewer. By default, Sentinet uses customized version of this open-source tool that implements OpenAPI v3. Click Show in Viewer menu option to open external viewer in a new browser window.

Figure. REST API documentation shown in the external Swagger Viewer (by default, local customized copy on the Swagger UI).

Important

Swagger UI uses client-side browser script. That means that the client script will be able to successfully make a Try it out call to an external API’s endpoint under two conditions:

1. There is no conflict with Cross-Origin Resource Sharing (CORS). This conflict can be resolved by Sentinet Administrative Console users by configuring tested API with support for CORS either with all default * values, or Allowed Origins value with the server address of the Developer Portal, for example: https://SentinetServer.
2. Tested API’s endpoint and Sentinet Administrative Console browser address use the same (https) protocol (http protocol may be acceptable, but unlikely to happen because Administrative Console usually is not allowed to be accessed through clear text http protocol).

Sentinet can be configured with any other external Swagger viewer or editor in the web.config file of the Repository Web Services application via swaggerViewerUrl attribute as shown below in the web.config file fragment where it uses online version of Swagger UI tool:

<nevatech.vsb.repository>
  ...
  <metadata policyVersion="Default" timeout="120" maximumReferences="100"
      serializer="Auto"
      swaggerViewerUrl="http://petstore.swagger.io/?url={0}"/>
  ...
</nevatech.vsb.repository>

Reload Metadata

Metadata for any existing physical service can be updated by reloading its Swagger/ OpenAPI document(s). This feature requires a careful usage as it can cause undesirable results especially when physical service is already virtualized through an active virtual service. Most often, Reload feature is used when changes to an existing physical service are not too “drastic” (for example, new operation is added or existing operation is removed).

Figure. Reload menu option.