개발자 포털에 API 제공

Red Hat 3scale API Management 2.14

올바르게 구성된 개발자 포털은 API 관리 기능을 많이 제공합니다.

Red Hat Customer Content Services

법적 공지

초록

이 가이드에서는 Red Hat 3scale API Management 2.14의 개발자 포털 사용에 대해 설명합니다.

머리말

API(애플리케이션 프로그래밍 인터페이스)를 정의하는 OpenAPI 문서는 개발자 포털의 기반입니다.

Red Hat 문서에 관한 피드백 제공

문서 개선을 위한 의견에 감사드립니다.

개선 사항을 제안하려면 Jira 문제를 열고 제안된 변경 사항을 설명합니다. 귀하의 요청을 신속하게 처리할 수 있도록 가능한 한 자세한 정보를 제공하십시오.

사전 요구 사항

Red Hat 고객 포털 계정이 있어야 합니다. 이 계정을 사용하면 Red Hat Jira Software 인스턴스에 로그인할 수 있습니다. 계정이 없는 경우 계정을 생성하라는 메시지가 표시됩니다.

절차

다음 링크를 클릭합니다. 문제 생성.
요약 텍스트 상자에 문제에 대한 간략한 설명을 입력합니다.
설명 텍스트 상자에 다음 정보를 입력합니다.
- 문제를 발견한 페이지의 URL입니다.
- 문제에 대한 자세한 설명입니다.
  다른 필드에 있는 정보는 기본값에 따라 그대로 둘 수 있습니다.
생성 을 클릭하여 Jira 문제를 문서 팀에 제출합니다.

피드백을 제공하기 위해 시간을 내어 주셔서 감사합니다.

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 API Management를 사용한 OpenAPI 사양 3.0 사용” 에서 참조하십시오.

사전 요구 사항

API를 정의하는 OpenAPI 문서입니다.
3scale 2.14 인스턴스 테넌트의 인증 정보(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. 3scale API Management에서 OpenAPI 문서를 가져오는 명령줄 옵션

3scale CLI(명령줄 인터페이스)는 3scale에서 관리하려는 API를 정의하는 OpenAPI 문서를 가져오기 위한 몇 가지 옵션을 제공합니다. 다음은 openapi 옵션에 대한 도움말 정보입니다.

Copy to Clipboard Toggle word wrap

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

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

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

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

설명 형식 명령줄 사용

표 1.1. OpenAPI 정의 탐지
설명	형식	명령줄 사용
파일 이름 경로에서 OpenAPI 정의 탐지. 형식은 파일 이름 확장에서 자동으로 감지됩니다.	JSON 및 yaml	Copy to Clipboard Toggle word wrap `$ 3scale import openapi -d <destination> /path/to/your/spec/file.[json\|yaml\|yml]`
URL에서 OpenAPI 정의 탐지. 형식은 URL의 경로 확장에서 자동으로 감지됩니다.	JSON 및 yaml	Copy to Clipboard Toggle word wrap `$ 3scale import openapi -d <destination> http[s]://domain/resource/path.[json\|yaml\|yml]`
stdin 에서 OpenAPI 정의 탐지. OpenAPI 리소스의 명령줄 매개 변수는 입니다. 형식은 구문 분석기를 사용하여 내부적으로 자동으로 감지됩니다.	JSON 및 yaml	Copy to Clipboard Toggle word wrap `$ tool_to_read_openapi_from_source \| 3scale import openapi -d <destination> -`

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

JSON 및 yaml

Copy to Clipboard Toggle word wrap

3scale import openapi -d <destination> /path/to/your/spec/file.[json|yaml|yml]

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

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

JSON 및 yaml

Copy to Clipboard Toggle word wrap

3scale import openapi -d <destination> http[s]://domain/resource/path.[json|yaml|yml]

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

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

JSON 및 yaml

Copy to Clipboard Toggle word wrap

tool_to_read_openapi_from_source | 3scale import openapi -d <destination> -

$ tool_to_read_openapi_from_source | 3scale import openapi -d <destination> -

2장. OpenAPI 사양 구성 방법

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

사전 요구 사항

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

2.1. 3scale API Management를 사용한 OpenAPI 사양 3.0 사용

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

Swagger-ui 가 OAS 3.0을 지원하도록 개발자 포털에서 업데이트되었습니다.
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 사양을 지원하려면 기본 문서 페이지의 다음 내용이 필요합니다.

Copy to Clipboard Toggle word wrap

{% 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>

{% 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을 계속 사용하려면 템플릿을 업데이트해야 합니다.

이는 구성할 템플릿입니다.

Copy to Clipboard Toggle word wrap

{% 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>

{% 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>

템플릿을 업데이트하려면 기본 문서 페이지를 개발자 포털을 OAS 3.0으로 구성하는 데 포함된 스니펫으로 교체합니다.

2.2. 3scale API Management를 사용한 OpenAPI 사양 2.0 사용

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

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

OAS 2.0 사양을 지원하려면 기본 문서 페이지의 다음 내용이 필요합니다.

Copy to Clipboard Toggle word wrap

<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>

<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에 대한 지원이 도입됨에 따라 구현 방법이 여러 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 유성 태그 및 새로운 부분 shared/swagger_ui 로 교체하십시오.

Copy to Clipboard Toggle word wrap

{% cdn_asset /swagger-ui/2.2.10/swagger-ui.js %}
{% cdn_asset /swagger-ui/2.2.10/swagger-ui.css %}

{% include 'shared/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 >은 로드하려는 사양의 시스템 이름입니다.
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
```
window.swaggerUi.options['url'] = "{{provider.api_specs.<SPEC_SYSTEM_NAME>.url}}";
```
```
window.swaggerUi.options['url'] = "{{provider.api_specs.<SPEC_SYSTEM_NAME>.url}}";
```

II 부. 개발자 포털의 API 문서

3장. 3scale에 ActiveDocs 추가

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

OpenAPI Specification (OAS) 을 사용하면 API에 대한 기능 문서가 있어 개발자가 API를 탐색, 테스트 및 통합하는 데 도움이 됩니다.

3.1. 3scale에서 ActiveDocs 설정

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

사전 요구 사항

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

절차

관리 포털에서 [your_API_name] → ActiveDocs 로 이동합니다. 3scale은 API에 대한 서비스 사양 목록을 표시합니다. 처음에는 비어 있습니다.
원하는 만큼 서비스 사양을 추가할 수 있습니다. 일반적으로 각 서비스 사양은 API 중 하나에 해당합니다. 예를 들어 3scale에는 서비스 관리, 계정 관리, NSX, Thanosing과 같은 각 3scale API에 대한 사양 이 있습니다.
새 사양 생성을 클릭합니다.
새 서비스 사양을 추가하면 다음을 제공합니다.
- 이름
- 시스템 이름
  이는 개발자 포털의 서비스 사양을 참조하는 데 필요합니다.
- 사양을 게시할지 여부를 선택합니다. 게시하지 않으면 개발자 포털에서 새 사양을 사용할 수 없습니다.
  참고
  생성하지만 새 사양을 게시하지 않으면 나중에 게시를 위해 사용할 수 있습니다.
- 사용에만 해당하는 설명을 추가합니다.
- API JSON 사양을 추가합니다.
  OpenAPI Specification (OAS) 에서 제안한 사양에 따라 API 사양을 생성합니다. 이 튜토리얼에서는 이미 API의 유효한 OAS 호환 사양을 가지고 있다고 가정합니다.

첫 번째 ActiveDoc으로 작업

첫 번째 ActiveDoc을 추가한 후 [your_API_name] → ActiveDocs 에 나열된 것을 확인할 수 있습니다. 필요에 따라 편집하거나 삭제하거나 공개에서 비공개로 전환할 수 있습니다. API에서 분리하거나 다른 API에 연결할 수 있습니다. 모든 ActiveDocs가 API에 연결되어 있는지 여부 → Developer Portal → ActiveDocs.

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

ActiveDoc의 모양은 다음과 같습니다.

4장. 3scale API Management OpenAPI 사양으로 사용하기 위해 OpenAPI 문서를 작성하는 방법

코드를 읽기만 하려면 모든 예제가 OAS Petstore 예제 소스 코드에 있습니다.

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

사전 요구 사항

REST API에 대한 OpenAPI 사양(OAS) 호환 사양은 개발자 포털의 ActiveDocs의 전원을 켜기 위해 필요합니다.

OAS는 사양만 있는 것은 아닙니다. 또한 전체 기능 프레임워크를 제공합니다.

여러 언어(NodeJS, Scala 등)로 리소스 사양을 위한 서버입니다.
사양 파일을 사용하고 흥미로운 UI를 생성하는 HTML/CSS/Javascripts 자산 세트입니다.
Swagger 호환 서버에서 클라이언트 라이브러리를 자동으로 생성할 수 있는 OAS 코드원 프로젝트. 여러 최신 언어로 클라이언트 측 라이브러리 생성 지원.

4.1. 3scale API Management 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 API Management를 사용한 OpenAPI 사양 3.0 사용” 에서 참조하십시오.

사전 요구 사항

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

절차

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

결과

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

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

3scale 확장 OAS는 개발자 포털 대화형 API 문서에 필요한 특정 기능을 수용할 수 있도록 여러 가지 방법으로 확장되었습니다.

API 키 자동 채우기.

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를 기반으로 한 문서를 반환합니다.
DELETE /api/pets/{id}
ID를 기반으로 단일 페이크를 삭제합니다.

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

사용자 키 매개변수

user_key: {user_key}

user_key 는 API 요청에 API 소비자가 보냅니다. API 소비자는 이러한 키를 3scale 관리자의 개발자 포털을 가져옵니다. 키를 수신할 때 3scale 관리자는 서비스 관리 API를 사용하여 3scale에 대한 권한 부여 검사를 수행해야 합니다.

OpenAPI 사양에 대한 자세한 내용

API 소비자의 경우 cURL 호출에 표시된 API의 문서는 다음과 같습니다.

Copy to Clipboard Toggle word wrap

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}"

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. 두 형식 모두 서명됩니다.
가능한 형식의 숫자: float 및 double.
일반 문자열.
가능한 형식의 문자열: 바이트, 날짜, 날짜, 암호 및 바이너리입니다.
부울.

추가 리소스

4.4. OAS 설계 및 편집 도구

다음 툴은 API를 정의하는 OpenAPI 사양을 설계 및 편집하는 데 유용합니다.

오픈 소스 Apicurio Studio 를 사용하면 웹 기반 애플리케이션에서 OpenAPI 기반 API를 디자인하고 편집할 수 있습니다. Apicurio Studio는 디자인 보기를 제공하므로 OpenAPI 사양에 대한 자세한 지식이 필요하지 않습니다. 소스 뷰를 사용하면 전문가 사용자가 YAML 또는 JSON에서 직접 편집할 수 있습니다. 자세한 내용은 Apicurio Studio 시작하기를 참조하십시오.
Red Hat은 OpenShift의 Fuse Online에 포함된 API DestinationRule이라는 Apicurio Studio의 경량 버전도 제공합니다. 자세한 내용은 API 공급자 통합 개발 및 배포를 참조하십시오.
JSON 편집기 Online 은 JSON 표기법을 잘 알고 있는 경우 유용합니다. 이는 컴팩트 JSON에 매우 형식을 제공하고 JSON 오브젝트 브라우저를 제공합니다.
Swagger 편집기 를 사용하면 브라우저에서 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 Key를 사용하는 서비스 애플리케이션의 키를 반환합니다. OAuth 및 OpenID Connect도 이전 버전과의 호환성을 위해 지원됩니다.

참고

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

API 키 인증 예

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

Copy to Clipboard Toggle word wrap

"parameters": [
  {
    "name": "user_key",
    "in": "query",
    "description": "Your API access key",
    "required": true,
    "schema": {
      "type": "string"
    },
    "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"
  }
]

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

5장. ActiveDocs 및 OAuth

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

사전 요구 사항

Red Hat Single Sign-On 인스턴스를 설정하고 OpenID Connect 통합을 구성해야 합니다. 설정 방법에 대한 자세한 내용은 OpenID Connect 통합 설명서를 참조하십시오.
또한 ActiveDocs 설정 방법에 대해 잘 알고 있어야 합니다. 3scale에 ActiveDocs 추가 및 OpenAPI 사양 생성 을 참조하십시오.

5.1. 3scale API Management 사양의 클라이언트 인증 정보 및 리소스 소유자 흐름의 예

첫 번째 예제는 3scale 사양에서 OAuth 2.0 클라이언트 인증 정보 흐름을 사용하는 API의 예입니다. 이 API는 모든 경로를 수락하고 요청에 대한 정보를 반환합니다(path, request 매개변수, 헤더 등). echo API는 유효한 액세스 토큰을 통해서만 액세스할 수 있습니다. API 사용자는 액세스 토큰으로 자격 증명(client_id 및 client_secret)을 교환한 후에만 해당 API를 호출할 수 있습니다.

사용자가 ActiveDocs에서 API를 호출할 수 있으려면 액세스 토큰을 요청해야 합니다. OAuth 권한 부여 서버를 호출하기만 하므로 OAuth 토큰 끝점에 대한 ActiveDocs 사양을 생성할 수 있습니다. 이를 통해 ActiveDocs 내에서 이 끝점에 대한 호출을 허용합니다. 이 경우 클라이언트 인증 정보 흐름의 경우 Swagger JSON 사양은 다음과 같습니다.

Copy to Clipboard Toggle word wrap

{
  "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"
            ]
          }
        ]
      }
    }
  }
}

{
  "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 흐름의 경우 사용자 이름 및 암호 및 액세스 토큰을 발행하는 데 필요한 기타 매개변수에 대한 매개 변수를 추가합니다. 이 클라이언트 자격 증명 흐름 예제의 경우 서명된 사용자에 대한 3scale 값과 grant_type에서 채워질 수 있는 client_id 및 client_secret 을 전송합니다.

다음으로 echo API의 ActiveDocs 사양에서 client_id 및 client_secret 대신 access_token 매개변수를 추가합니다.

Copy to Clipboard Toggle word wrap

{
  "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
          }
        ]
      }
    }
  }
}

{
  "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
          }
        ]
      }
    }
  }
}

그러면 정상적으로 Developer Portal에 ActiveDocs를 포함할 수 있습니다. 이 경우 OAuth 끝점이 먼저 표시되도록 표시되는 순서를 지정하려면 다음과 같습니다.

Copy to Clipboard Toggle word wrap

{% 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>

{% 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 문서가 자동화됩니다.

사전 요구 사항

REST API에 대한 OpenAPI 사양(OAS) 호환 사양은 개발자 포털의 ActiveDocs의 전원을 켜기 위해 필요합니다.

절차

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

참고

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

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

Copy to Clipboard Toggle word wrap

{% 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>

{% 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 2.0을 사용한 개발자 포털 구성

Copy to Clipboard Toggle word wrap

<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>

<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>

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

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

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

Copy to Clipboard Toggle word wrap

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

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

사양 소스 window.swaggerUi.options['url'] = "SWAGGER_JSON_URL";, 은 주석 블록 외부에 있습니다.

검증 단계

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

법적 공지

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.

개발자 포털에 API 제공

올바르게 구성된 개발자 포털은 API 관리 기능을 많이 제공합니다.

머리말

Red Hat 문서에 관한 피드백 제공

I 부. OpenAPI 사양

1장. OpenAPI 사양 소개

1.1. 3scale API Management에서 OpenAPI 문서를 가져오는 명령줄 옵션

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

2장. OpenAPI 사양 구성 방법

2.1. 3scale API Management를 사용한 OpenAPI 사양 3.0 사용

2.1.1. OAS 3.0으로 개발자 포털 구성

2.2. 3scale API Management를 사용한 OpenAPI 사양 2.0 사용

2.3. Swagger 사용자 인터페이스 2.1.3을 2.2.10으로 업그레이드

II 부. 개발자 포털의 API 문서

3장. 3scale에 ActiveDocs 추가

3.1. 3scale에서 ActiveDocs 설정

4장. 3scale API Management OpenAPI 사양으로 사용하기 위해 OpenAPI 문서를 작성하는 방법

4.1. 3scale API Management ActiveDocs 및 OAS 설정

4.2. OpenAPI 문서 예: Petstore API

4.3. 추가 OAS 사양 정보

4.4. OAS 설계 및 편집 도구

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

5장. ActiveDocs 및 OAuth

5.1. 3scale API Management 사양의 클라이언트 인증 정보 및 리소스 소유자 흐름의 예

5.2. 개발자 포털에 ActiveDocs 게시

법적 공지

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

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

Red Hat 소개

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links