Red Hat Summit Red Hat Summit지원콘솔개발자평가판 시작연락처

개발자 포털에서 API 제공

Red Hat 3scale API Management 2.13

적절하게 구성된 개발자 포털은 API 관리를 위한 많은 기능을 제공합니다.

Red Hat Customer Content Services

초록

이 가이드에서는 Red Hat 3scale API Management 2.13에서 개발자 포털을 사용하는 방법을 설명합니다.

머리말
링크 복사

API를 정의하는 OpenAPI 문서는 개발자 포털의 기반이 됩니다.

보다 포괄적 수용을 위한 오픈 소스 용어 교체
링크 복사

Red Hat은 코드, 문서, 웹 속성에서 문제가 있는 용어를 교체하기 위해 최선을 다하고 있습니다. 먼저 마스터(master), 슬레이브(slave), 블랙리스트(blacklist), 화이트리스트(whitelist) 등 네 가지 용어를 교체하고 있습니다. 이러한 변경 작업은 작업 범위가 크므로 향후 여러 릴리스에 걸쳐 점차 구현할 예정입니다. 자세한 내용은 CTO Chris Wright의 메시지에서 참조하십시오.

I 부. OpenAPI Specification
링크 복사

1장. OpenAPI 사양 소개
링크 복사

Red Hat 3scale API Management에서 OAS(OpenAPI Specification)를 사용하면 OpenAPI 문서를 최적으로 관리할 수 있습니다. OAS(OpenAPI Specification)는 기존 서비스를 업데이트하거나 새 서비스를 생성하는 도구를 제공합니다.

다음은 3scale의 OAS에 대한 특별한 고려 사항입니다.

사전 요구 사항

  • API를 정의하는 OpenAPI 문서입니다.
  • 3scale 2.13 인스턴스 테넌트의 인증 정보(token 또는 provider_key).

OAS를 사용하면 3scale에서 다음 기능을 사용할 수 있습니다.

참고

OpenAPI 문서를 가져올 때 ActiveDocs를 만들거나 업데이트합니다. 3scale 사양으로 사용할 OpenAPI 문서를 작성하는 방법을 참조하십시오.

  • 3scale 서비스 system_name 을 OAS의 info.title 필드로 설정하는 선택적 매개변수로 전달하는 기능

  • OpenAPI 사양에 정의된 각 작업에 대해 메서드가 생성됩니다.

    • 메서드 이름은 operation.operationId 필드에서 가져옵니다.

  • 기존 매핑 규칙은 새 API 정의를 가져오기 전에 삭제됩니다.

    • 명령을 실행하기 전에 존재하는 경우 메서드가 삭제되지 않습니다.
  • OpenAPI 사양에 정의된 각 작업에 대해 매핑 규칙이 생성됩니다.

  • 다음 채널 중 하나에서 OpenAPI 정의 리소스를 제공합니다.

    • 사용 가능한 경로의 파일 이름
    • URL 형식 - toolbox는 지정된 주소에서 다운로드하려고 합니다.
    • stdin 표준 입력 스트림에서 읽습니다.

1.1. OpenAPI 문서를 3scale로 가져오기 위한 명령행 옵션
링크 복사

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
                                                  command
Copy to Clipboard Toggle word wrap

1.2. API 사양을 가져올 다양한 소스
링크 복사

API 사양을 가져오기 위한 3scale 관리자로 사용할 수 있는 다양한 소스가 있습니다. 파일 이름 경로, URL, stdin 에서 OpenAPI 정의를 탐지하기 위한 사용 옵션을 보여주는 다음 표에 설명되어 있습니다.

Expand
표 1.1. OpenAPI 정의 감지
설명형식명령줄 사용

파일 이름 경로에서 OpenAPI 정의 감지. 형식은 파일 이름 확장에서 자동으로 탐지됩니다.

JSON 및 yaml 

$ 3scale import openapi -d <destination> /path/to/your/spec/file.[json|yaml|yml]
Copy to Clipboard Toggle word wrap

URL에서 OpenAPI 정의 탐지. 형식은 URL의 경로 확장에서 자동으로 탐지됩니다.

JSON 및 yaml 

$ 3scale import openapi -d <destination> http[s]://domain/resource/path.[json|yaml|yml]
Copy to Clipboard Toggle word wrap

stdin 에서 OpenAPI 정의 감지. OpenAPI 리소스의 명령행 매개 변수는 - 입니다. 형식은 구문 분석기를 사용하여 내부적으로 자동으로 감지됩니다.

JSON 및 yaml 

$ tool_to_read_openapi_from_source | 3scale import openapi -d <destination> -
Copy to Clipboard Toggle word wrap

2장. OpenAPI 사양 구성 방법
링크 복사

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

사전 요구 사항

  • API를 정의하는 OpenAPI 문서입니다.
  • 3scale 2.13 인스턴스 테넌트의 인증 정보(token 또는 provider_key).

2.1. 3scale로 OpenAPI Specification 3.0 사용
링크 복사

3scale은 OAS 3.0 사용에 대한 다음과 같은 지원을 제공합니다.

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

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

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

2.1.1. OAS 3.0을 사용하여 개발자 포털 구성
링크 복사

이 스니펫에는 새 버전의 swagger-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>
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

템플릿을 업데이트하려면 기본 문서 페이지를 2.1.1절. “OAS 3.0을 사용하여 개발자 포털 구성” 에 포함된 스니펫로 교체합니다.

2.2. OpenAPI Specification 2.0 사용과 3scale
링크 복사

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

  • 템플릿을 수동으로 업그레이드해야 합니다.
  • 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>
Copy to Clipboard Toggle word wrap

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" %} Liquid 태그의 존재 여부에 따라 달라집니다. 3scale에서 Swagger 2.2.10에 대한 지원이 도입되면서 구현 방법이 여러 cdn_asset 로 변경되고 유동 태그가 포함됩니다.

참고

Swagger UI 2.1.3 이하 버전의 경우 3scale은 기존의 active_docs Liquid 태그 방법을 사용하여 UI를 호출합니다.

사전 요구 사항

  • 관리자 액세스 권한이 있는 3scale 인스턴스.
  • Swagger UI 2.1.3이 포함된 3scale 인스턴스입니다.

절차

  1. 3scale 관리 포털에 로그인합니다.
  2. 개발자 포털 → 문서 페이지로 이동합니다. Swagger UI 구현을 업데이트하려는 페이지

  3. 코드 창의 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' %}
    Copy to Clipboard Toggle word wrap

  4. 선택 사항: 기본적으로 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}}";
    Copy to Clipboard Toggle word wrap

II 부. 개발자 포털에 있는 API 문서
링크 복사

3장. 3scale에 ActiveDocs 추가
링크 복사

3scale은 API에 대한 대화형 문서를 작성하는 프레임워크를 제공합니다.

OAS(OpenAPI Specification) 를 사용하면 API에 대한 기능 문서가 있어 개발자가 API를 탐색하고 테스트 및 통합할 수 있습니다.

3.1. 3scale에서 ActiveDocs 설정
링크 복사

3scale 사용자 인터페이스의 API에 ActiveDocs를 추가하여 API에 대한 대화형 문서를 만들기 위한 프레임워크를 가져올 수 있습니다.

사전 요구 사항

  • API를 정의하는 OpenAPI 문서입니다.
  • 3scale 2.13 인스턴스 테넌트의 인증 정보(token 또는 provider_key).

절차

  1. 관리 포털에서 [your_API_name] → ActiveDocs 로 이동합니다. 3scale은 API의 서비스 사양 목록을 표시합니다. 처음에는 비어 있습니다.

    원하는 만큼 서비스 사양을 추가할 수 있습니다. 일반적으로 각 서비스 사양은 API 중 하나에 해당합니다. 예를 들어 3scale에는 서비스 관리, 계정 관리, 분석 및 청구와 같은 3scale API 각각에 대한 사양이 있습니다.

  2. 새 사양 생성을 클릭합니다.

    새 서비스 사양을 추가할 때 다음을 제공합니다.

    • 이름
    • 시스템 이름. 개발자 포털에서 서비스 사양을 참조하는 데 필요합니다.

    • 사양을 게시할지 여부를 선택합니다. 게시하지 않으면 개발자 포털에서 새 사양을 사용할 수 없습니다.

      참고

      새 사양을 만들 수는 없지만 새 사양을 게시하지 않으면 나중에 선택한 시점에 게시에 계속 사용할 수 있습니다.

    • 사용 용도로만 사용할 수 있는 설명을 추가합니다.

    • API JSON 사양을 추가합니다.

      OAS(OpenAPI Specification) 에서 제안한 사양에 따라 API 사양을 생성합니다. 이 튜토리얼에서는 이미 API의 유효한 OAS 호환 사양이 있다고 가정합니다.

첫 번째 ActiveDoc로 작업

첫 번째 ActiveDoc을 추가한 후 [your_API_name] → ActiveDocs 에 나열된 것을 확인할 수 있습니다. 필요에 따라 편집하거나, 삭제하거나, public에서 private로 전환할 수 있습니다. API에서 분리하거나 다른 API에 연결할 수 있습니다. NetNamespace → 개발자 포털 → ActiveDocs에서 API에 연결되어 있는지 여부에 관계없이 모든 ActiveDocs 를 볼 수 있습니다.

서비스 사양을 제공한 이름을 클릭하여 ActiveDocs가 어떻게 보이는지 미리 볼 수 있습니다(예: Pet Store). 사양이 아직 게시되지 않은 경우에도 이 작업을 수행할 수 있습니다.

ActiveDoc의 예는 다음과 같습니다.

ActiveDocs 새로운 사양 보기

4장. 3scale OpenAPI 사양으로 사용할 OpenAPI 문서를 작성하는 방법
링크 복사

코드를 읽으려면 OAS Petstore 예제 소스 코드 의 모든 예제가 있습니다.

3scale ActiveDocs는 Swagger 라는 RESTful 웹 서비스의 사양을 기반으로 합니다( Wordnik에서). 이 예제는 Extended OpenAPI Specification Petstore 예제 를 기반으로 하며 OpenAPI Specification 2.0 사양 문서에서 모든 사양 데이터를 작성합니다.

사전 요구 사항

  • REST API의 OAS(OpenAPI Specification) 호환 사양은 개발자 포털의 ActiveDocs의 전원을 켜야 합니다.

OAS는 단순한 사양이 아닙니다. 또한 전체 기능 프레임워크를 제공합니다.

  • 여러 언어(NodeJS, Scala 등)의 리소스 사양을 위한 서버입니다.
  • 표준 파일을 사용하고 매력적인 UI를 생성하는 HTML/CSS/Javascripts 자산 세트입니다.
  • OAS codegen 프로젝트 - Swagger 호환 서버에서 자동으로 클라이언트 라이브러리 생성을 허용합니다. 여러 가지 최신 언어로 클라이언트 쪽 라이브러리를 만들 수 있도록 지원합니다.Supports to create client-side libraries in a number of modern languages.

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 Specification 3.0 사용” 을 참조하십시오.

사전 요구 사항

  • 개발자 포털에서 사용된 템플릿이 관리 포털에 지정된 동일한 OAS 버전을 구현하는지 확인합니다.

절차

  1. OAS와 호환되는 API 사양을 빌드합니다.
  2. 관리 포털에 사양을 추가합니다.

결과

API에 대한 대화형 문서를 사용할 수 있습니다. API 소비자는 개발자 포털을 통해 API에 요청을 보낼 수 있습니다.

이미 API의 OAS 호환 사양이 있는 경우 개발자 포털에 추가할 수 있습니다. ActiveDocs 구성에 대한 튜토리얼을 참조하십시오.

3scale은 개발자 포털 대화형 API 설명서에 필요한 특정 기능을 수용하기 위해 OAS를 여러 가지 방법으로 확장합니다.

  • API 키 자동 입력
  • CORS가 아닌 API에 대한 호출을 허용하는 OAS 프록시

4.2. OpenAPI 문서 예: Petstore API
링크 복사

원본 소스에서 사양을 읽으려면 OpenAPI Specification 을 참조하십시오.

OAS 사이트에는 API를 정의하는 OpenAPI 문서의 여러 예가 있습니다. 예를 들어 학습하려는 경우 OAS API 팀에서 Petstore API의 예제를 따를 수 있습니다.

Petstore API는 매우 간단한 API입니다. 이는 프로덕션이 아닌 학습 도구로 사용됩니다.

스패시 저장소 API 방법

Petstore API는 4 가지 방법으로 구성됩니다.

  • GET /api/pets - 시스템에서 모든 반려동물 반환
  • POST /api/pets - 저장소에 새 개 생성
  • GET /api/pets/{id} - 단일 ID를 기반으로 하는 원근을 반환합니다.
  • DELETE /api/pets/{id} - ID를 기반으로 한 개씩 삭제

Petstore API는 3scale과 통합되어 있으므로 인증을 위해 매개변수를 더 추가해야 합니다. 예를 들어 사용자 키 인증 방법을 사용하는 경우 API 소비자는 각 요청의 헤더에 사용자 키 매개 변수를 배치해야 합니다. 다른 인증 방법에 대한 자세한 내용은 인증 패턴을 참조하십시오.

사용자 키 매개변수

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}"
Copy to Clipboard Toggle word wrap

4.3. 추가 OAS 사양 정보
링크 복사

문서가 OAS Petstore 문서처럼 보이려면 관련 Petstore swagger.json 파일과 같은 Swagger 호환 사양을 만들어야 합니다. 이 사양을 기본으로 사용하여 ActiveDocs를 테스트할 수 있습니다. 그러나 이 API는 해당 API가 아닙니다.

OAS는 JSON으로 인코딩된 해시에 매핑되는 리소스 선언을 사용합니다. Petstore swagger.json 파일을 예제로 사용하고 각 오브젝트에 대해 알아보십시오.

OAS 오브젝트

이는 API 사양의 루트 문서 오브젝트입니다. 가장 높은 수준의 모든 필드를 나열합니다.

info 오브젝트

info 오브젝트는 API에 대한 메타데이터를 제공합니다. 이 내용은 ActiveDocs 페이지에 나와 있습니다.

Route 오브젝트

경로 오브젝트에는 개별 엔드포인트에 대한 상대 경로가 있습니다. 경로는 전체 URL을 구성하기 위해 basePath에 추가됩니다. ACL(액세스 제어 목록) 제약 조건으로 인해 경로가 비어 있을 수 있습니다.

오브젝트가 아닌 매개변수는 프리미티브 데이터 유형을 사용합니다. Swagger에서 기본 데이터 유형은 JSON-Schema Draft 4 에서 지원하는 유형을 기반으로 합니다. 추가 기본 데이터 유형 파일이 있지만 3scale은 API 끝점에 CORS가 활성화된 경우에만 사용합니다. CORS를 활성화하면 업로드가 api-docs 게이트웨이를 통과하지 않으며, 이 게이트웨이는 거부됩니다.

현재 OAS는 다음 dataTypes 를 지원합니다:

  • 가능한 형식이 int32 및 int64인 정수입니다. 두 형식 모두 서명됩니다.
  • 가능한 형식: float 및 double
  • 일반 문자열
  • 바이트, 날짜, 날짜, 암호 및 바이너리 형식 문자열
  • 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 편집기를 배포할 수 있습니다.

4.5. API 인증 정보 자동 채우기 ActiveDocs auto-fill of API credentials
링크 복사

API 인증 정보의 자동 채우기는 3scale ActiveDocs의 OAS에 유용한 확장입니다. API 인증 모드에 따라 다음 값을 사용하여 x-data-threescale-name 필드를 정의할 수 있습니다.

  • user_keys: API 키 인증을 사용하는 서비스의 애플리케이션에 대한 사용자 키를 반환합니다.
  • app_ids: 앱 ID/App 키를 사용하는 서비스 애플리케이션의 ID를 반환합니다. OAuth 및 OpenID Connect도 이전 버전과의 호환성을 위해 지원됩니다.
  • app_keys: 앱 ID/App 키를 사용하는 서비스 애플리케이션의 키를 반환합니다. OAuth 및 OpenID Connect도 이전 버전과의 호환성을 위해 지원됩니다.
참고

X -data-threescale-name 필드는 ActiveDocs 도메인 외부에서 무시되는 OAS 확장입니다.

API 키 인증 예

다음 예제에서는 API 키 인증에 "x-data-threescale-name": "user_keys" 를 사용하는 방법을 보여줍니다. 

"parameters": [
  {
    "name": "user_key",
    "in": "query",
    "description": "Your API access key",
    "required": true,
    "schema": {
      "type": "string"
    },
    "x-data-threescale-name": "user_keys"
  }
]
Copy to Clipboard Toggle word wrap

x-data-threescale-name 으로 선언된 매개변수의 경우 사양에 구성된 값에 따라 5개의 최신 키, 사용자 키, 앱 ID 또는 앱 키가 있는 드롭다운 목록이 표시됩니다. 따라서 값을 복사하여 붙여넣지 않고도 입력을 자동으로 채울 수 있습니다.

로그인 시 자동 입력

5장. ActiveDocs 및 OAuth
링크 복사

ActiveDocs를 사용하면 사용자가 한 곳에서 OAuth 사용 API를 테스트하고 호출할 수 있습니다.

사전 요구 사항

첫 번째 예는 3scale 사양에서 OAuth 2.0 클라이언트 인증 정보 흐름을 사용하는 API입니다. 이 API는 모든 경로를 수락하고 요청에 대한 정보를 반환합니다(path, 요청 매개변수, 헤더 등). 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"
            ]
          }
        ]
      }
    }
  }
}
Copy to Clipboard Toggle word wrap

리소스 소유자 OAuth 흐름의 경우 액세스 토큰을 발행하기 위해 사용자 이름 및 암호 및 기타 매개변수에 대한 매개변수를 추가합니다. 이 클라이언트 인증 정보 흐름 예의 경우, 서명된 사용자의 3scale 값과 grant_type을 채울 수 있는 client_id 및 client_secret 를 보내고 있습니다.

그런 다음 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
          }
        ]
      }
    }
  }
}
Copy to Clipboard Toggle word wrap

그런 다음 정상적으로 개발자 포털에 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>
Copy to Clipboard Toggle word wrap

5.2. 개발자 포털에서 ActiveDocs 게시
링크 복사

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

사전 요구 사항

  • REST API의 OAS(OpenAPI Specification) 호환 사양은 개발자 포털의 ActiveDocs의 전원을 켜야 합니다.

절차

  • 개발자 포털의 모든 페이지에 다음 스니펫을 추가합니다. 이 작업은 3scale 관리 포털을 통해 수행해야 합니다.

    참고

    SERVICE_NAME 은 서비스 사양의 시스템 이름이어야 하며, 이 이름은 example의 Pet_store 입니다.

    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>
    Copy to Clipboard Toggle word wrap

    OAS 2.0을 사용한 개발자 포털 구성

    <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 behavior
      // 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>
    Copy to Clipboard Toggle word wrap

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

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

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

$(function () {
 window.swaggerUi.options['url'] = "SWAGGER_JSON_URL";
 window.swaggerUi.load();
});
Copy to Clipboard Toggle word wrap

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

검증 단계

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

법적 공지
링크 복사

Copyright © 2024 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubredditYoutubeTwitter

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

Red Hat을 사용하는 고객은 신뢰할 수 있는 콘텐츠가 포함된 제품과 서비스를 통해 혁신하고 목표를 달성할 수 있습니다. 최신 업데이트를 확인하세요.

보다 포괄적 수용을 위한 오픈 소스 용어 교체

Red Hat은 코드, 문서, 웹 속성에서 문제가 있는 언어를 교체하기 위해 최선을 다하고 있습니다. 자세한 내용은 다음을 참조하세요.Red Hat 블로그.

Red Hat 소개

Red Hat은 기업이 핵심 데이터 센터에서 네트워크 에지에 이르기까지 플랫폼과 환경 전반에서 더 쉽게 작업할 수 있도록 강화된 솔루션을 제공합니다.

Theme

© 2026 Red Hat맨 위로 이동