4장. 3scale OpenAPI 사양으로 사용할 OpenAPI 문서를 작성하는 방법
코드를 읽으려면 모든 예제가 OAS Petstore 예제 소스 코드에 있습니다.
3scale ActiveDocs는 Swagger 라는 RESTful 웹 서비스의 사양을 기반으로 합니다( Warge). 이 예는 Extended OpenAPI Specification Petstore 예제 를 기반으로 하며 OpenAPI 사양 2.0 사양 문서의 모든 사양 데이터를 가져옵니다.
사전 요구 사항
- 개발자 포털에서 ActiveDocs를 구동하려면 REST API에 대한 OAS(OpenAPI Specification) 호환 사양이 필요합니다.
OAS는 단순한 사양이 아닙니다. 또한 다음과 같은 완전한 기능 프레임워크를 제공합니다.
- 여러 언어로 리소스 사양을 위한 서버(NodeJS, Scala 등).
- 사양 파일을 사용하고 매력적인 UI를 생성하는 HTML/CSS/Javascripts 자산 세트입니다.
- Swagger 호환 서버에서 클라이언트 라이브러리를 자동으로 생성할 수 있는 OAS codegen 프로젝트. 여러 최신 언어로 클라이언트 쪽 라이브러리를 만들 수 있도록 지원.
4.1. 3scale ActiveDocs 및 OAS 설정
ActiveDocs는 OAS의 인스턴스입니다. ActiveDocs를 사용하면 자체 OAS 서버를 실행하거나 대화형 문서의 사용자 인터페이스 구성 요소를 처리할 필요가 없습니다. 3scale 개발자 포털에서 대화형 문서가 제공되고 렌더링됩니다.
3scale 2.8은 ActiveDocs의 제한된 지원과 함께 OAS 3.0을 도입했습니다. 즉, 자동 완성과 같은 ActiveDocs에서 작동하는 일부 기능은 아직 완전히 통합되지 않았으며, 결과적으로 3scale의 기본값은 새 계정을 만들 때 OAS 2.0으로 설정됩니다. OAS 3.0 및 ActiveDocs에 대한 자세한 내용은 2.1절. “3scale을 사용한 OpenAPI 사양 3.0 사용” 에서 참조하십시오.
사전 요구 사항
- 개발자 포털에서 사용된 템플릿이 관리 포털에 지정된 것과 동일한 OAS 버전을 구현하는지 확인합니다.
절차
- OAS와의 API 호환 사양을 구축합니다.
- 관리 포털에 사양을 추가합니다.
결과
API에 대한 대화형 설명서를 사용할 수 있습니다. API 소비자는 개발자 포털을 통해 API에 요청을 보낼 수 있습니다.
이미 OAS 호환 API 사양이 있는 경우 개발자 포털에 추가할 수 있습니다. ActiveDocs 구성에 대한 자습서를 참조하십시오.
3scale은 개발자 포털 대화형 API 설명서에 필요한 특정 기능을 수용하기 위해 여러 가지 방법으로 OAS를 확장합니다.
- API 키 자동 입력
- CORS가 아닌 API에 대한 호출을 허용하는 OAS 프록시