5.2. 개발자 포털에 ActiveDocs 게시

이 튜토리얼이 끝나면 개발자 포털에 ActiveDocs를 게시하고 API 문서가 자동화됩니다.

사전 요구 사항

  • 개발자 포털에서 ActiveDocs를 구동하려면 REST API에 대한 OAS(OpenAPI Specification) 호환 사양이 필요합니다.

절차

  • 다음 코드 조각을 개발자 포털의 모든 페이지의 콘텐츠에 추가합니다. 3scale 관리 포털을 통해 이 작업을 수행해야 합니다.

    참고

    SERVICE_NAME 은 예제에서 Pet _store 인 서비스 사양의 시스템 이름이어야 합니다.

    <h1>Documentation</h1>
    <p>Use our live documentation to learn about Echo API</p>
    {% active_docs version: "2.0" services: "SERVICE_NAME" %}
    {% 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 () {
        {% comment %}
          // you have access to swaggerUi.options object to customize its behaviour
          // such as setting a different docExpansion mode
          window.swaggerUi.options['docExpansion'] = 'none';
          // or even getting the swagger specification loaded from a different url
          window.swaggerUi.options['url'] = "http://petstore.swagger.io/v2/swagger.json";
        {% endcomment %}
        window.swaggerUi.load();
      });
    </script>

개발자 포털에 ActiveDocs를 게시할 때 다음과 같은 몇 가지 추가 고려 사항이 있습니다.

  • 한 페이지에서 하나의 서비스만 지정할 수 있습니다. 여러 사양을 표시하려는 경우 가장 좋은 방법은 다른 페이지에서 수행하는 것입니다.
  • 이 코드 조각에는 기본적으로 개발자 포털의 기본 레이아웃에 포함된œ가 필요합니다. 기본 레이아웃에서 종속성을 제거하는 경우 ActiveDocs가 포함된 페이지에 이 종속성을 추가해야 합니다.
  • 관리 포털에서 태그가 활성화되어 있는지 확인합니다.
  • {{ '{% active_docs 버전에 사용된 버전: "2.0" ' }}%} 는 Swagger 사양에 해당해야 합니다.

외부 소스에서 사양을 가져오려면 다음과 같이 JavaScript 코드를 변경합니다.

$(function () {
 window.swaggerUi.options['url'] = "SWAGGER_JSON_URL";
 window.swaggerUi.load();
});

사양 소스 window.swaggerUi.options['url'] = "SWAGGER_JSON_URL"을 포함하는 행은 주석 블록 외부에 있습니다.

검증 단계

OpenAPI 사양을 생성하고 3scale에 추가한 후 API 개발자가 사용할 개발자 포털에 사양을 게시하고 연결해야 합니다.