개발자 포털에서 API 제공
올바르게 구성된 개발자 포털은 API 관리를 위한 다양한 기능을 제공합니다.
초록
preface
API를 정의하는 OpenAPI 문서는 개발자 포털의 기초입니다.
보다 포괄적 수용을 위한 오픈 소스 용어 교체
Red Hat은 코드, 문서, 웹 속성에서 문제가 있는 용어를 교체하기 위해 최선을 다하고 있습니다. 먼저 마스터(master), 슬레이브(slave), 블랙리스트(blacklist), 화이트리스트(whitelist) 등 네 가지 용어를 교체하고 있습니다. 이러한 변경 작업은 작업 범위가 크므로 향후 여러 릴리스에 걸쳐 점차 구현할 예정입니다. 자세한 내용은 CTO Chris Wright의 메시지에서 참조하십시오.
I 부. OpenAPI 사양
1장. OpenAPI 사양 소개
Red Hat 3scale API Management에서 OpenAPI 사양(OAS)은 OpenAPI 문서를 최적으로 관리하는 데 도움이 됩니다. OAS(OpenAPI Specification)는 기존 서비스를 업데이트하거나 새 서비스를 생성하는 툴을 제공합니다.
다음은 3scale의 OAS에 대한 특별한 고려 사항입니다.
- 3scale toolbox를 사용하여 OpenAPI 사양(OpenAPI 문서)을 가져올 수도 있습니다. OpenAPI 정의 가져오기 를 참조하십시오.
- OAS 3.0과 관련하여 3scale 2.8은 변경 사항을 도입했습니다. 자세한 내용은 2.1절. “3scale을 사용한 OpenAPI 사양 3.0 사용” 에서 참조하십시오.
사전 요구 사항
- API를 정의하는 OpenAPI 문서입니다.
-
3scale 2.11 인스턴스 테넌트의 자격 증명(
토큰또는provider_key).
OAS를 사용하면 3scale에서 다음 기능을 사용할 수 있습니다.
OpenAPI 문서를 가져올 때 ActiveDocs를 생성하거나 업데이트합니다. 3scale 사양으로 사용하기 위해 OpenAPI 문서를 작성하는 방법을 참조하십시오.
-
3scale service
system_name을 OAS에서 info.title 필드로 기본값으로 설정하는 선택적 매개 변수로 전달하는 기능. OpenAPI 사양에 정의된 각 작업에 대해 메서드가 생성됩니다.
-
메서드 이름은
operation.operationId필드에서 가져옵니다.
-
메서드 이름은
새 API 정의를 가져오기 전에 기존의 모든 매핑 규칙이 삭제됩니다.
- 명령을 실행하기 전에 메서드가 있는 경우 삭제되지 않습니다.
- OpenAPI 사양에 정의된 각 작업에 대해 매핑 규칙이 생성됩니다.
다음 채널 중 하나는 OpenAPI 정의 리소스를 제공합니다.
- 사용 가능한 경로의 파일 이름
- URL 형식 - toolbox는 지정된 주소에서 다운로드하려고 시도합니다.
- stdin 표준 입력 스트림에서 읽습니다.
1.1. 3scale에서 OpenAPI 문서 가져오기를 위한 명령줄 옵션
3scale CLI(명령줄 인터페이스)는 3scale에서 관리할 API를 정의하는 OpenAPI 문서를 가져오기 위한 여러 가지 옵션을 제공합니다. 다음은 openapi 옵션에 대한 도움말 정보입니다.
NAME
openapi - Import API definition in OpenAPI specification
USAGE
3scale import openapi [opts] -d <dst> <spec>
DESCRIPTION
Using an API definition format like OpenAPI, import to your 3scale API
OPTIONS
-d --destination=<value> 3scale target instance.
Format: "http[s]://<authentication>@3scale_domain"
-t --target_system_name=<value> Target system name
OPTIONS FOR IMPORT
-c --config-file=<value> 3scale toolbox
configuration file
(default:
$HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even
for server connections
otherwise considered
insecure
-v --version Prints the version of this
command1.2. API 사양을 가져올 다양한 소스
API 사양을 가져오는 데 3scale 관리자로서 다양한 소스를 사용할 수 있습니다. 이러한 내용은 파일 이름 경로, URL 및 stdin 에서 OpenAPI 정의를 탐지하기 위한 사용 옵션을 보여주는 다음 표에 설명되어 있습니다.
표 1.1. OpenAPI 정의 탐지
| 설명 | 형식 | 명령줄 사용 |
|---|---|---|
| 파일 이름 경로에서 OpenAPI 정의 감지. 형식은 filename 확장자에서 자동으로 탐지됩니다. | JSON 및 yaml |
$ 3scale import openapi -d <destination> /path/to/your/spec/file.[json|yaml|yml] |
| URL에서 OpenAPI 정의 감지. 형식은 URL의 경로 확장자에서 자동으로 탐지됩니다. | JSON 및 yaml |
$ 3scale import openapi -d <destination> http[s]://domain/resource/path.[json|yaml|yml] |
|
stdin 에서 OpenAPI 정의 탐지. OpenAPI 리소스의 명령줄 매개 변수는 | JSON 및 yaml |
$ tool_to_read_openapi_from_source | 3scale import openapi -d <destination> - |
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"> </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으로 개발자 포털 구성” 에 포함된 코드 조각으로 바꿉니다.
2.2. 3scale을 사용한 OpenAPI 사양 2.0 사용
ActiveDocs에 OAS 2.0 사양을 추가하고 다음 사항을 고려하여 개발자 포털에 표시할 수 있습니다.
- 템플릿을 수동으로 업그레이드해야 합니다.
- ActiveDoc에는 요청을 가져올 때 자격 증명 주입과 같은 추가 기능이 없으며 서비스 이름과 같은 실제 데이터를 사용하여 자동 완성할 수 없습니다.
OAS 2.0 사양을 지원하려면 기본 문서 페이지에 다음 내용이 필요합니다.
<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>2.3. Swagger 사용자 인터페이스 2.1.3을 2.2.10으로 업그레이드
Swagger UI 2.1.3이 포함된 3scale 버전을 사용하는 경우 Swagger UI 버전 2.2.10으로 업그레이드할 수 있습니다.
3scale 개발자 포털의 이전 Swagger UI 2.1.3 구현은 단일 {% active_docs 버전을 사용합니다. "2.0" %} 설명서 페이지의 유동 태그. 3scale에서 Swagger 2.2.10에 대한 지원이 도입되면서 구현 방법이 multiple cdn_asset 로 변경되어 유동 태그가 포함됩니다.
Swagger UI 2.1.3 이전 버전의 경우 3scale은 레거시 active_docs 유동 태그 방법을 사용하여 UI를 호출합니다.
사전 요구 사항
- 관리자 액세스 권한이 있는 3scale 인스턴스.
- Swagger UI 2.1.3을 포함하는 3scale 인스턴스.
절차
- 3scale 관리 포털에 로그인합니다.
-
개발자 포털→문서페이지로 이동하거나 Swagger UI 구현을 업데이트할 페이지로 이동합니다. 코드 창의
Draft탭에서{% active_docs 버전을 교체합니다. "2.0" %}cdn_asset유동 태그 및 새로운 부분공유/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' %}선택 사항: 기본적으로 Swagger UI는 API > ActiveDocs에 게시된 ActiveDocs 사양을 로드합니다. window.
swaggerUi.행을 추가하여 다른 사양을 로드합니다. 여기서load(); 행 앞에 다음 window.swaggerUi.options<SPEC_SYSTEM_NAME>은 로드하려는 사양의 시스템 이름입니다.window.swaggerUi.options['url'] = "{{provider.api_specs.<SPEC_SYSTEM_NAME>.url}}";
II 부. 개발자 포털의 API 문서
3장. 3scale에 ActiveDocs 추가
3scale은 API에 대한 대화형 문서를 만들 수 있는 프레임워크를 제공합니다.
O AS(OpenAPI Specification) 에는 개발자가 API를 탐색, 테스트 및 통합하는 데 도움이 되는 API에 대한 기능 문서가 있습니다.
3.1. 3scale에서 ActiveDocs 설정
3scale 사용자 인터페이스의 API에 ActiveDocs를 추가하여 API의 대화형 문서를 생성하기 위한 프레임워크를 가져올 수 있습니다.
사전 요구 사항
- API를 정의하는 OpenAPI 문서입니다.
-
3scale 2.11 인스턴스 테넌트의 자격 증명(
토큰또는provider_key).
절차
관리 포털의 [your_API_name] → ActiveDocs 로 이동합니다. 3scale에는 API에 대한 서비스 사양 목록이 표시됩니다. 처음에는 비어 있습니다.
원하는 만큼 많은 서비스 사양을 추가할 수 있습니다. 일반적으로 각 서비스 사양은 API 중 하나에 해당합니다. 예를 들어 3scale에는 서비스 관리, 계정 관리, 분석 및 청구와 같은 3scale API에 대한 사양이 있습니다.
Create a new spec (새 사양 만들기)을 클릭합니다.
새 서비스 사양을 추가할 때 다음을 제공합니다.
- 이름
- 시스템 이름. 이는 개발자 포털의 서비스 사양을 참조하는 데 필요합니다.
사양을 게시할지 여부를 선택합니다. 게시하지 않으면 새 사양은 개발자 포털에서 사용할 수 없습니다.
참고를 생성하지만 새 사양을 게시하지 않으면 선택한 나중에 게시할 수 있는 상태로 유지됩니다.
- 사용자의 소비용으로만 사용되는 설명을 추가합니다.
API JSON 사양을 추가합니다.
O AS(OpenAPI Specification) 에서 제안한 사양에 따라 API 사양을 생성합니다. 이 튜토리얼에서는 이미 API의 유효한 OAS 준수 사양을 가지고 있다고 가정합니다.
첫 번째 ActiveDoc 작업
첫 번째 ActiveDoc을 추가한 후 [your_API_name] → ActiveDocs 에 나열된 내용을 확인할 수 있습니다. 필요에 따라 편집하거나 삭제하거나 공용에서 개인으로 전환할 수 있습니다. API에서 분리하거나 다른 API에 연결할 수 있습니다. 대상 → 개발자 포털 → ActiveDocs의 API에 연결되어 있는지 여부에 관계없이 모든 ActiveDocs 를 볼 수 있습니다.
서비스 사양(예: Pet Store)을 선택한 이름을 클릭하여 ActiveDocs의 상태를 미리 볼 수 있습니다. 사양이 아직 게시되지 않았더라도 이 작업을 수행할 수 있습니다.
ActiveDoc은 다음과 같습니다.

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 프록시
4.2. OpenAPI 문서 예: Petstore API
원래 소스에서 사양을 읽으려면 OpenAPI 사양을 참조하십시오.
OAS 사이트에는 API를 정의하는 OpenAPI 문서의 여러 예제가 있습니다. 예제로 배우고 싶다면 OAS API 팀에서 Petstore API 예제를 따를 수 있습니다.
Petstore API는 매우 간단한 API입니다. 이는 프로덕션용이 아닌 학습 도구로 사용됩니다.
Petstore API 방법
Petstore API는 다음 4가지 방법으로 구성됩니다.
-
GET /api/pets- 시스템에서 모든 애완동물을 반환합니다. -
POST /api/pets- 저장소에 새 애완동물 생성 -
GET /api/pets/{id}- 단일 ID를 기반으로 ID를 반환합니다. -
DELETE /api/pets/{id}- ID를 기반으로 하나의 애완동물 삭제
Petstore API는 3scale과 통합되어 있으므로 인증을 위해 매개변수를 추가해야 합니다. 예를 들어 사용자 키 인증 방법을 사용하면 API 소비자는 각 요청의 헤더에 user key 매개 변수를 배치해야 합니다. 다른 인증 방법에 대한 자세한 내용은 인증 패턴을 참조하십시오.
사용자 키 매개변수
user_key: {user_key}
user_key 는 API 소비자가 요청에 따라 API로 전송합니다. API 소비자는 3scale 관리자의 개발자 포털을 가져옵니다. 키를 받으면 3scale 관리자는 Service Management API를 사용하여 3scale에 대해 권한 부여 검사를 수행해야 합니다.
OpenAPI 사양에 대한 추가 정보
API 소비자의 경우 cURL 호출에 표시된 API 설명서는 다음과 같습니다.
curl -X GET "http://example.com/api/pets?tags=TAGS&limit=LIMIT" -H "user_key: {user_key}"
curl -X POST "http://example.com/api/pets" -H "user_key: {user_key}" -d "{ "name": "NAME", "tag": "TAG", "id": ID }"
curl -X GET "http://example.com/api/pets/{id}" -H "user_key: {user_key}"
curl -X DELETE "http://example.com/api/pets/{id}" -H "user_key: {user_key}"4.3. 추가 OAS 사양 정보
설명서를 OAS Petstore 문서처럼 표시하려면 관련 Petstore swagger.json 파일과 같은 Swagger 호환 사양을 생성해야 합니다. 즉시 사용 가능한 이 사양을 사용하여 ActiveDocs를 테스트할 수 있습니다. 그러나 이것은 API가 아닙니다.
OAS는 JSON으로 인코딩된 해시에 매핑되는 리소스 선언을 사용합니다. Petstore swagger.json 파일을 예제로 사용하고 각 오브젝트에 대해 알아봅니다.
OAS 개체
API 사양의 루트 문서 오브젝트입니다. 모든 최상위 필드를 나열합니다.
info 오브젝트
info 오브젝트는 API에 대한 메타데이터를 제공합니다. 이 내용은 ActiveDocs 페이지에 나와 있습니다.
경로 오브젝트
paths 오브젝트에는 개별 엔드포인트에 대한 상대 경로가 포함됩니다. 전체 URL을 구성하기 위해 경로가 basePath에 추가됩니다. 경로 는 ACL(액세스 제어 목록) 제약 조건으로 인해 비어 있을 수 있습니다.
오브젝트가 아닌 매개변수는 기본 데이터 유형을 사용합니다. Swagger에서 기본 데이터 유형은 JSON-Schema Draft 4 에서 지원하는 유형을 기반으로 합니다. 추가 기본 데이터 유형 파일이 있지만 3scale은 API 엔드포인트에 CORS가 활성화된 경우에만 사용합니다. CORS를 활성화하면 업로드가 거부되는 api-docs 게이트웨이를 통과하지 않습니다.
현재 OAS는 다음과 같은 dataTypes 를 지원합니다 :
- int32 및 int64 형식이 가능한 정수입니다. 두 형식 모두 서명됩니다.
- 가능한 형식이 있는 번호: floating 및 double
- 일반 문자열
- 가능한 형식이 있는 문자열: byte, date, date-time, password 및 바이너리
- boolean
추가 리소스
4.4. OAS 설계 및 편집 도구
다음 툴은 API를 정의하는 OpenAPI 사양을 설계하고 편집하는 데 유용합니다.
오픈 소스 Apicurio Studio 를 사용하면 웹 기반 애플리케이션에서 OpenAPI 기반 API를 설계하고 편집할 수 있습니다. Apicurio Studio는 OpenAPI 사양에 대한 자세한 지식이 필요하지 않도록 설계 보기를 제공합니다. 소스 뷰를 사용하면 전문가 사용자가 YAML 또는 JSON에서 직접 편집할 수 있습니다. 자세한 내용은 Apicurio Studio 시작하기를 참조하십시오.
또한 Red Hat은 OpenShift의 Fuse Online에 포함된 API Designer라는 경량 버전의 Apicurio Studio를 제공합니다. 자세한 내용은 API 공급자 통합 개발 및 배포를 참조하십시오.
- JSON Editor Online 은 JSON 표기법을 잘 알고 있는 경우 유용합니다. JSON을 압축할 수 있는 형식을 제공하고 JSON 개체 브라우저를 제공합니다.
- Swagger Editor 를 사용하면 브라우저에서 YAML로 작성된 OAS API 사양을 생성 및 편집하고 실시간으로 미리 볼 수 있습니다. 3scale 관리 포털에서 나중에 업로드할 수 있는 유효한 JSON 사양을 생성할 수도 있습니다. 제한된 기능으로 라이브 데모 버전을 사용하거나 OAS Editor를 배포할 수 있습니다.
4.5. ActiveDocs API 키 자동 입력
API 키 자동 입력은 3scale ActiveDocs에서 OAS를 확장하는 데 유용합니다. API 인증 모드에 따라 다음 값을 사용하여 x-data-threescale-name 필드를 정의할 수 있습니다.
-
user_keys: API 키 인증만 사용하는 서비스 애플리케이션에 대한 사용자 키를 반환합니다. -
app_ids: App ID/App Key를 사용하는 서비스 애플리케이션의 ID를 반환합니다. 이전 버전과의 호환성을 위해 OAuth 및 OpenID Connect도 지원됩니다. -
app_keys: App ID/App Key를 사용하는 서비스 애플리케이션에 대한 키를 반환합니다. 이전 버전과의 호환성을 위해 OAuth 및 OpenID Connect도 지원됩니다.
API 키 인증 예
다음 예제에서는 API 키 인증에만 "x-data-threescale-name": "user_keys" 를 사용하는 방법을 보여줍니다.
"parameters": [
{
"name": "user_key",
"description": "Your access API Key",
"type": "string",
"in": "query",
"x-data-threescale-name": "user_keys",
"required": true
},
]
x-data-threescale-name 필드는 ActiveDocs 도메인 외부에서 무시되는 OAS 확장입니다.
App ID/App 키 인증 모드는 애플리케이션 ID를 나타내는 매개 변수에 "x-data-threescale-name": "app_ids" 를 지정하고 애플리케이션 키를 나타내는 매개 변수에 "x-data-threescale-name": "app_keys" 를 지정합니다.
매개 변수를 선언하면 ActiveDocs 사용자에게 다음 스크린샷과 같이 자동으로 Developer Portal에 로그인하라는 메시지가 표시됩니다.

사용자가 이미 로그인한 경우 ActiveDocs는 키 복사 및 붙여넣기 없이도 즉시 테스트할 수 있도록 관련된 최신 5개의 키를 표시합니다.

5장. ActiveDocs 및 OAuth
ActiveDocs를 사용하면 한 곳에서 OAuth 지원 API를 테스트하고 호출할 수 있습니다.
사전 요구 사항
- Red Hat Single Sign-On 인스턴스를 설정하고 OpenID Connect 통합을 구성해야 합니다. 설정 방법에 대한 자세한 내용은 OpenID Connect 통합 문서를 참조하십시오.
- 또한 ActiveDocs 설정 방법에 익숙해야 합니다. 3scale에 ActiveDocs 추가 및 OpenAPI 사양 생성을 참조하십시오.
5.1. 3scale 사양에서 클라이언트 인증 정보 및 리소스 소유자 흐름의 예
이 첫 번째 예는 3scale 사양의 OAuth 2.0 클라이언트 인증 정보 흐름을 사용하는 API용입니다. 이 API는 경로를 수락하고 요청에 대한 정보(경로, 요청 매개변수, 헤더 등)를 반환합니다. Echo API는 유효한 액세스 토큰을 사용하는 경우에만 액세스할 수 있습니다. API 사용자는 자격 증명(client_id 및 )을 액세스 토큰으로 교환한 후에만 호출할 수 있습니다.
client_secret
사용자가 ActiveDocs에서 API를 호출하려면 액세스 토큰을 요청해야 합니다. OAuth 인증 서버에 대한 호출일 뿐입니다. OAuth 토큰 엔드포인트에 대한 ActiveDocs 사양을 생성할 수 있습니다. 이렇게 하면 ActiveDocs 내에서 이 끝점에 대한 호출이 허용됩니다. 이 경우 클라이언트 인증 정보 흐름의 경우 Swagger JSON 사양은 다음과 같습니다.
{
"swagger": "2.0",
"info": {
"version": "v1",
"title": "OAuth for Echo API",
"description": "OAuth2.0 Client Credentails Flow for authentication of our Echo API.",
"contact": {
"name": "API Support",
"url": "http://www.swagger.io/support",
"email": "support@swagger.io"
}
},
"host": "red-hat-sso-instance.example.com",
"basePath": "/auth/realms/realm-example/protocol/openid-connect",
"schemes": [
"http"
],
"paths": {
"/token": {
"post": {
"description": "This operation returns the access token for the API. You must call this before calling any other endpoints.",
"operationId": "oauth",
"parameters": [
{
"name": "client_id",
"description": "Your client id",
"type": "string",
"in": "query",
"required": true
},
{
"name": "client_secret",
"description": "Your client secret",
"type": "string",
"in": "query",
"required": true
},
{
"name": "grant_type",
"description": "OAuth2 Grant Type",
"type": "string",
"default": "client_credentials",
"required": true,
"in": "query",
"enum": [
"client_credentials",
"authorization_code",
"refresh_token",
"password"
]
}
]
}
}
}
}리소스 소유자 OAuth 흐름의 경우 액세스 토큰을 발행하기 위해 필요한 사용자 이름 및 암호 및 기타 매개 변수에 대한 매개변수를 추가합니다. 이 클라이언트 자격 증명 흐름 예의 경우 client_id 및 client_secret 을 보내며 이는 로그인한 사용자의 3scale 값과 grant_type에서 채울 수 있습니다.
그런 다음 Echo API의 ActiveDocs 사양에 client _ id 및 client_ secret 대신 access_ token 매개 변수를 추가합니다.
{
"swagger": "2.0",
"info": {
"version": "v1",
"title": "Echo API",
"description": "A simple API that accepts any path and returns information about the request",
"contact": {
"name": "API Support",
"url": "http://www.swagger.io/support",
"email": "support@swagger.io"
}
},
"host": "echo-api.3scale.net",
"basePath": "/v1/words",
"schemes": [
"http"
],
"produces": [
"application/json"
],
"paths": {
"/{word}.json": {
"get": {
"description": "This operation returns information about the request (path, request parameters, headers, etc.),
"operationId": "wordsGet",
"summary": "Returns the path of a given word",
"parameters": [
{
"name": "word",
"description": "The word related to the path",
"type": "string",
"in": "path",
"required": true
},
{
"name": "access_token",
"description": "Your access token",
"type": "string",
"in": "query",
"required": true
}
]
}
}
}
}그런 다음 정상적으로 ActiveDocs를 개발자 포털에 포함할 수 있습니다. 이 경우 OAuth 끝점을 먼저 표시하도록 표시하는 순서를 지정하려면 다음과 같이 표시됩니다.
{% active_docs version: "2.0" services: "oauth" %}
<script type="text/javascript">
$(function () {
window.swaggerUi.load(); // <-- loads first swagger-ui
// do second swagger-ui
var url = "/swagger/spec/echo-api.json";
window.anotherSwaggerUi = new SwaggerUi({
url: url,
dom_id: "another-swagger-ui-container",
supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
onComplete: function(swaggerApi, swaggerUi) {
$('#another-swagger-ui-container pre code').each(function(i, e) {hljs.highlightBlock(e)});
},
onFailure: function(data) {
log("Unable to Load Echo-API-SwaggerUI");
},
docExpansion: "list",
transport: function(httpClient, obj) {
log("[swagger-ui]>>> custom transport.");
return ApiDocsProxy.execute(httpClient, obj);
}
});
window.anotherSwaggerUi.load();
});
</script>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 개발자가 사용할 개발자 포털에 사양을 게시하고 연결해야 합니다.