此内容没有您所选择的语言版本。

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>

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

Copy to Clipboard

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>

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

Copy to Clipboard

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>

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

Copy to Clipboard

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:

Log in to your 3scale AMP admin portal
Navigate to the Developer Portal Documentation page, or the page in which you want to update your Swagger UI implementation

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' %}

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

{% include 'shared/swagger_ui' %}

Copy to Clipboard

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}}";
```
```
window.swaggerUi.options['url'] = "{{provider.api_specs.<SPEC_SYSTEM_NAME>.url}}";
```
Copy to Clipboard

此内容没有您所选择的语言版本。

Chapter 2. Configuring OAS

2.1. Using OAS 3.0 with 3scale

2.1.1. Configuring the Developer Portal with OAS 3.0

2.1.2. Updating the Developer Portal with OAS 3.0

2.2. Using OAS 2.0 with 3scale

2.3. Upgrade Swagger UI 2.1.3 TO 2.2.10

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links