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 개발자가 사용할 개발자 포털에 사양을 게시하고 연결해야 합니다.