2장. OpenAPI 사양 구성 방법

OpenAPI 사양이 3scale으로 작동하려면 사용하려는 버전에 맞게 올바르게 구성해야 합니다.

사전 요구 사항

  • API를 정의하는 OpenAPI 문서입니다.
  • 3scale 2.11 인스턴스 테넌트의 자격 증명(토큰 또는 provider_key).

2.1. 3scale을 사용한 OpenAPI 사양 3.0 사용

3scale은 OAS 3.0을 사용할 수 있는 다음과 같은 지원을 제공합니다.

  • Swagger-ui 가 개발자 포털에서 OAS 3.0을 지원하도록 업데이트되었습니다
  • Swagger-ui 는 이제 웹팩 자산(node_modules)으로 포함됩니다. 이전에는 CDN(Content Delivery Networks)에서 추가되었습니다.
  • 관리 포털에서 새로운 OAS 3.0 문서는 by swagger-ui 가 제공하는 기능을 사용하여 적절하게 식별되고 적절하게 처리됩니다. 이 기능에는 개발자 포털의 구성이 필요합니다.

ActiveDocs에 OAS 3.0 사양을 추가하고 다음 사항을 고려하여 개발자 포털에 표시할 수 있습니다.

  • 템플릿을 수동으로 업그레이드해야 합니다.
  • ActiveDoc에는 요청을 가져올 때 자격 증명 주입과 같은 추가 기능이 없으며 서비스 이름과 같은 실제 데이터를 사용하여 자동 완성할 수 없습니다.

2.1.1. OAS 3.0으로 개발자 포털 구성

이 스니펫에는 새 버전의wagger -ui 가 포함되어 있으며 첫 번째 ActiveDoc을 렌더링합니다. OAS 2.0도 렌더링되지만 일반적인 ActiveDocs 기능은 없습니다.

OAS 3.0 사양을 지원하려면 기본 문서 페이지에 다음 내용이 필요합니다.

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

OAS 3.0으로 개발자 포털 업데이트

3scale 2.8에 OAS 3.0을 구성했으며 OAS 3.0을 계속 사용하려면 템플릿을 업데이트해야 합니다.

구성할 템플릿입니다.

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

템플릿을 업데이트하려면 기본 문서 페이지를 2.1.1절. “OAS 3.0으로 개발자 포털 구성” 에 포함된 코드 조각으로 바꿉니다.