Chapter 2. How to configure OpenAPI Specification

For the OpenAPI Specification to work with 3scale, it needs to configured correctly for the version you intend to use.

Prerequisites

  • An OpenAPI document that defines your API.
  • A 3scale 2.11 instance tenant’s credentials (token or provider_key).

2.1. OpenAPI Specification 3.0 usage with 3scale

3scale provides the following support for using OAS 3.0:

  • swagger-ui has been updated in the Developer Portal to support OAS 3.0
  • swagger-ui is now included as a webpack asset (node_modules). Formerly, it was added from Content Delivery Networks (CDNs).
  • In the Admin Portal, any new OAS 3.0 document is identified automatically and processed accordingly, by using the features provided by swagger-ui. Note that this functionality requires configuration in the Developer Portal.

You can add OAS 3.0 specifications to ActiveDocs and display them in the Developer Portal, considering the following points:

  • You must upgrade the templates manually.
  • The ActiveDoc does not have additional features such as credential injection when attempting requests, and autocompletion using real data like service name.

2.1.1. Configure the Developer Portal with OAS 3.0

This snippet includes the new version of swagger-ui, and renders the first ActiveDoc available. Note that it will also render OAS 2.0 but without any of the usual ActiveDocs features.

Support for OAS 3.0 specifications requires the following content in the default documentation page: 

{% content_for javascripts %}
 {{ 'active_docs.js' | javascript_include_tag }}
{% endcontent_for %}

{% assign spec = provider.api_specs.first %}

<h1>Documentation</h1>

<div class="swagger-section">
 <div id="message-bar" class="swagger-ui-wrap"></div>
 <div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</div>

<script type="text/javascript">
 (function () {
   var url = "{{spec.url}}";
   var serviceEndpoint = "{{spec.api_product_production_public_base_url}}"
   SwaggerUI({ url: url, dom_id: "#swagger-ui-container" }, serviceEndpoint);
 }());
</script>

Update the Developer Portal with OAS 3.0

If you have configured OAS 3.0 in 3scale 2.8 and want to continue using OAS 3.0, you need to update the template.

This is the template to configure: 

{% content_for javascripts %}
    {{ 'active_docs.js' | javascript_include_tag }}
{% endcontent_for %}

<h1>Documentation</h1>

<div class="swagger-section">
  <div id="message-bar" class="swagger-ui-wrap">&nbsp;</div>
  <div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</div>

<script type="text/javascript">
  (function () {
    var url = "{{provider.api_specs.first.url}}";

    SwaggerUI({ url: url, dom_id: "#swagger-ui-container" });
  }());
</script>

To update the template, replace the default Documentation page with the snippet included in Section 2.1.1, “Configure the Developer Portal with OAS 3.0”.

2.2. OpenAPI Specification 2.0 usage with 3scale

You can add OAS 2.0 specifications to ActiveDocs and display them in the Developer Portal, considering the following points:

  • You must upgrade the templates manually.
  • The ActiveDoc does not have additional features such as credential injection when attempting requests, and auto-completion using real data like service name.

Support for OAS 2.0 specifications requires the following content in the default documentation page: 

<h1>Documentation</h1>
{% cdn_asset /swagger-ui/2.2.10/swagger-ui.js %}
{% cdn_asset /swagger-ui/2.2.10/swagger-ui.css %}

{% include 'shared/swagger_ui' %}

<script type="text/javascript">
  $(function () {
    window.swaggerUi.options['url'] = "{{provider.api_specs.first.url}}";
    window.swaggerUi.load();
  });
</script>

2.3. Upgrading the Swagger user interface 2.1.3 to 2.2.10

If you are using a version of 3scale that contains Swagger UI 2.1.3, you can upgrade to Swagger UI version 2.2.10.

Previous implementations of Swagger UI 2.1.3 in the 3scale Developer Portal rely on the presence of a single {% active_docs version: "2.0" %} liquid tag in the Documentation page. With the introduction of support for Swagger 2.2.10 in 3scale, the implementation method changes to multiple cdn_asset and include liquid tags.

Note

For versions of Swagger UI 2.1.3 and earlier, 3scale continues to use the legacy active_docs liquid tag method to call the UI.

Prerequisites

  • A 3scale instance with administrator access.
  • A 3scale instance that contains Swagger UI 2.1.3.

Procedure

  1. Log in to your 3scale Admin Portal.
  2. Navigate to the Developer Portal → Documentation page, or the page in which you want to update your Swagger UI implementation

  3. In the Draft tab of the code pane, replace the {% active_docs version: "2.0" %} liquid tag with the cdn_asset liquid tag and the new partial shared/swagger_ui: 

    {% cdn_asset /swagger-ui/2.2.10/swagger-ui.js %}
{% cdn_asset /swagger-ui/2.2.10/swagger-ui.css %}

{% include 'shared/swagger_ui' %}

  4. Optional: By default, Swagger UI loads the ActiveDocs specification published in APIs > ActiveDocs. Load a different specification by adding the following window.swaggerUi.options line before the window.swaggerUi.load(); line, where <SPEC_SYSTEM_NAME> is the system name of the specification you want to load: 

    window.swaggerUi.options['url'] = "{{provider.api_specs.<SPEC_SYSTEM_NAME>.url}}";