Red Hat Summit Red Hat Summit지원콘솔개발자평가판 시작연락처

이 콘텐츠는 선택한 언어로 제공되지 않습니다.

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>
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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' %}
    Copy to Clipboard Toggle word wrap

  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}}";
    Copy to Clipboard Toggle word wrap
맨 위로 이동
Red Hat logoGithubredditYoutubeTwitter

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

Red Hat을 사용하는 고객은 신뢰할 수 있는 콘텐츠가 포함된 제품과 서비스를 통해 혁신하고 목표를 달성할 수 있습니다. 최신 업데이트를 확인하세요.

보다 포괄적 수용을 위한 오픈 소스 용어 교체

Red Hat은 코드, 문서, 웹 속성에서 문제가 있는 언어를 교체하기 위해 최선을 다하고 있습니다. 자세한 내용은 다음을 참조하세요.Red Hat 블로그.

Red Hat 소개

Red Hat은 기업이 핵심 데이터 센터에서 네트워크 에지에 이르기까지 플랫폼과 환경 전반에서 더 쉽게 작업할 수 있도록 강화된 솔루션을 제공합니다.

Theme

© 2025 Red Hat