Chapter 2. Configuring OAS

This documentation outlines the configuration procedures for OpenAPI Specification (OAS) in Red Hat 3scale API Management 2.9.

2.1. Using OAS 3.0 with 3scale

This section provides information about using OpenAPI Specification 3.0 (OAS 3.0) with 3scale.

You can configure 3scale with OAS 3.0, using a limited support. For example:

  • 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 will be identified automatically and processed accordingly, by using the features provided by swagger-ui. Note that this functionality requires a configuration on the Developer Portal side.

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 will not have additional features; such as credential injection when attempting requests, and autocompletion using real data like service name.

2.1.1. Configuring the Developer Portal with OAS 3.0

To configure OAS 3.0 in the Developer Portal, add a new page or replace the default Documentation page with the following snippet: 

{% 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>

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.

2.1.2. Updating 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 that you should have configured: 

{% 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, “Configuring the Developer Portal with OAS 3.0”.

2.2. Using OAS 2.0 with 3scale

This section provides information about using OpenAPI Specification 2.0 (OAS 2.0) 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 will not have additional features; such as credential injection when attempting requests, and autocompletion using real data like service name.

To configure OAS 2.0 in the Developer Portal, add a new page or replace the default Documentation page with the following snippet: 

<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. Upgrade Swagger UI 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

Previous versions of Swagger UI in 3scale will continue to be called using the legacy active_docs liquid tag method.

Perform the following steps to upgrade Swagger UI 2.1.3 to 2.2.10:

  1. Log in to your 3scale AMP 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 code pane replace the {% active_docs version: "2.0" %} liquid tag with the following assets 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. 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}}";