OpenAPI 사양에서 API 프록시 만들기 | Apigee Edge

이 튜토리얼에서는 Apigee Edge 관리 UI를 사용하여 OpenAPI 사양에서 Edge API 프록시를 만드는 방법을 알아봅니다. cURL과 같은 HTTP 클라이언트로 API 프록시를 호출하면 API 프록시가 요청을 Apigee 모의 대상 서비스로 전송합니다.

Open API Initiative 정보

"Open API Initiative(OAI)는 Swagger 사양에 따라 공급업체 중립적인 API 설명 형식을 생성, 진화, 홍보하는 데 중점을 두고 있습니다." Open API Initiative에 대한 상세 내용은 https://openapis.org를 참조하세요.

OpenAPI 사양에서는 표준 형식을 사용하여 RESTful API를 설명합니다. JSON 또는 YAML 형식으로 작성된 OpenAPI 사양을 머신에서 읽을 수 있지만 사람도 쉽게 읽고 이해할 수 있습니다. 사양은 기본 경로, 경로 및 동사, 헤더, 쿼리 매개변수, 작업, 콘텐츠 유형, 응답 설명과 같은 API 요소를 설명합니다. 또한 OpenAPI 사양은 일반적으로 API 문서를 생성하는 데 사용됩니다.

Apigee 모의 대상 서비스에 대한 정보

이 가이드에서 사용되는 Apigee 모의 대상 서비스는 Apigee에서 호스팅되며 간단한 데이터를 반환합니다. API 키 또는 액세스 토큰이 필요하지 않습니다. 실제로 웹브라우저에서 액세스할 수 있습니다. 다음을 클릭하여 사용해 보세요.

http://mocktarget.apigee.net

대상 서비스가 인사말 Hello, guest!를 반환합니다.

모의 대상 서비스에서 지원하는 전체 API 집합에 대한 자세한 내용은 다음을 클릭하여 확인하세요.

http://mocktarget.apigee.net/help

필요한 항목

Apigee Edge 계정. 계정이 없는 경우 Apigee Edge 계정 만들기의 안내에 따라 가입할 수 있습니다.
OpenAPI 사양. 이 가이드에서는 Apigee의 모의 대상 서비스인 http://mocktarget.apigee.net을 설명하는 mocktarget.yaml OpenAPI 사양을 사용합니다. 자세한 내용은 https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi을 참조하세요.
명령줄에서 API 호출을 수행하기 위해 머신에 설치된 cURL 또는 웹브라우저

API 프록시 만들기

에지

Edge UI를 사용하여 OpenAPI 사양에서 API 프록시를 만들려면 다음 안내를 따르세요.

https://apigee.com/edge에 로그인합니다.
기본 창에서 'API 프록시'를 클릭합니다.
또는 왼쪽 탐색 메뉴에서 개발 > API 프록시를 선택할 수 있습니다.
+프록시를 클릭합니다.
프록시 만들기 마법사에서 역방향 프록시 (가장 일반적) 템플릿에 대해 OpenAPI 사양 사용을 클릭합니다.
URL에서 가져오기를 클릭하고 다음 정보를 입력합니다.
- OpenAPI Spec URL: URL 필드에 있는 OpenAPI 사양에 관한 GitHub의 원시 콘텐츠 경로입니다.
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```
- 사양 이름: OpenAPI 사양의 이름(예시: 모의 대상)입니다.
  이 이름은 사양 저장소에 OpenAPI 사양을 저장하는 데 사용됩니다. 사양 관리를 참고하세요.

Import를 클릭합니다.

프록시 만들기 마법사의 세부정보 페이지가 표시됩니다. 필드는 다음 그림과 같이 OpenAPI 사양에 정의된 값을 사용하여 자동 입력됩니다.

다음 표에서는 OpenAPI 사양의 속성을 사용하여 미리 채워진 기본값을 설명합니다. 아래 표에는 사용된 속성이 나와 있는 OpenAPI 사양의 발췌 내용이 나와 있습니다.

필드	설명	기본 계정
이름	API 프록시 이름입니다. 예를 들면 `Mock-Target-API`입니다.	대시에 의해 공백이 교체된 OpenAPI 사양의 `title` 속성
기본 경로	조직 내에서 이 API 프록시를 고유하게 식별하는 경로 구성요소입니다. 이 API 프록시의 공개 URL은 조직 이름, 이 API 프록시가 배포된 환경, 이 기본 경로로 구성됩니다. 예를 들면 다음과 같습니다. `http://myorg-test.apigee.net/mock-target-api`	이름 필드 콘텐츠가 모두 소문자로 변환됨
설명	API 프록시의 설명입니다.	OpenAPI 사양의 `description` 속성
대상(기존 API)	이 API 프록시를 대신하여 호출된 대상 URL. 개방형 인터넷을 통해 액세스할 수 있는 모든 URL을 사용할 수 있습니다. 예를 들면 `http://mocktarget.apigee.net`입니다.	OpenAPI 사양의 `servers` 속성

다음은 OpenAPI 사양에서 필드를 미리 채우는 데 사용되는 속성을 보여주는 발췌문을 제공합니다.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...

설명 필드를 다음과 같이 수정합니다. API proxy for the Apigee mock target service endpoint.
다음을 클릭합니다.
일반 정책 페이지의 보안: 승인에서 통과 (승인 없음)가 선택되어 있는지 확인하고 다음을 클릭합니다.
흐름 페이지에서 모든 작업이 선택되어 있는지 확인합니다.
팁: 조건부 흐름은 OpenAPI 사양의 paths 객체 내에 정의된 작업에서 자동으로 생성됩니다. 조건부 흐름은 Edge에 '이 항목이 표시되면 이 로직을 수행'하라고 알립니다. 예를 들어 API 호출이 /xml 리소스(조건)에 대한 GET인 경우 조건부 흐름에 연결된 정책을 통해 응답을 JSON으로 변환합니다. 트랜잭션당 하나의 흐름(조건이 true로 평가되는 첫 번째 흐름)만 실행됩니다.
다음을 클릭합니다.
가상 호스트 페이지에서 기본값 및 보안을 선택하고 다음을 클릭합니다.
요약 페이지의 선택적 배포 아래에서 테스트 환경이 선택되어 있는지 확인하고 만들기 및 배포를 클릭합니다.

Apigee가 새 API 프록시를 만들어 테스트 환경에 배포합니다.
프록시 수정을 클릭하여 API 프록시의 개요 페이지를 표시합니다.

Classic Edge (Private Cloud)

기본 Edge UI를 사용하여 OpenAPI 사양에서 API 프록시를 만들려면 다음 안내를 따르세요.

https://apigee.com/edge에 로그인합니다.
기본 창에서 'API 프록시'를 클릭합니다.
또는 왼쪽 탐색 메뉴에서 개발 > API 프록시를 선택할 수 있습니다.
+프록시를 클릭합니다.
프록시 만들기 마법사에서 역방향 프록시 (가장 일반적)를 선택하고 OpenAPI 사용을 클릭합니다.
URL에서 가져오기를 클릭하고 OpenAPI 사양 이름을 입력한 다음, URL 필드에 OpenAPI 사양의 GitHub에 있는 원시 콘텐츠 경로를 입력합니다.

https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
선택을 클릭합니다.

다음을 클릭합니다.

프록시 만들기 마법사의 세부정보 페이지가 표시됩니다. 이 필드는 다음 그림과 같이 OpenAPI 사양에 정의된 값을 사용하여 미리 채워집니다.

다음 표에서는 OpenAPI 사양의 속성을 사용하여 미리 채워진 기본값을 설명합니다. 아래 표에는 사용된 속성이 나와 있는 OpenAPI 사양의 발췌 내용이 나와 있습니다.

필드	설명	기본 계정
Proxy Name	API 프록시 이름입니다. 예를 들면 `Mock-Target-API`입니다.	대시에 의해 공백이 교체된 OpenAPI 사양의 `title` 속성
프록시 기본 경로	조직 내에서 이 API 프록시를 고유하게 식별하는 경로 구성요소입니다. 이 API 프록시의 공개 URL은 조직 이름, 이 API 프록시가 배포된 환경, 이 기본 경로로 구성됩니다. 예를 들면 다음과 같습니다. `http://myorg-test.apigee.net/mock-target-api`	이름 필드 콘텐츠가 모두 소문자로 변환됨
Existing API	이 API 프록시를 대신하여 호출된 대상 URL. 개방형 인터넷을 통해 액세스할 수 있는 모든 URL을 사용할 수 있습니다. 예를 들면 `http://mocktarget.apigee.net`입니다.	OpenAPI 사양의 `servers` 속성
설명	API 프록시의 설명입니다.	OpenAPI 사양의 `description` 속성

다음은 OpenAPI 사양에서 필드를 미리 채우는 데 사용되는 속성을 보여주는 발췌문을 제공합니다.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...

설명 필드를 다음과 같이 수정합니다. API proxy for the Apigee mock target service endpoint.
다음을 클릭합니다.
흐름 페이지에서 모든 작업이 선택되어 있는지 확인합니다.
팁: 조건부 흐름은 OpenAPI 사양의 paths 객체 내에 정의된 작업에서 자동으로 생성됩니다. 조건부 흐름은 Edge에 '이 항목이 표시되면 이 로직을 수행'하라고 알립니다. 예를 들어 API 호출이 /xml 리소스(조건)에 대한 GET인 경우 조건부 흐름에 연결된 정책을 통해 응답을 JSON으로 변환합니다. 트랜잭션당 하나의 흐름(조건이 true로 평가되는 첫 번째 흐름)만 실행됩니다.
다음을 클릭합니다.
보안 페이지에서 보안 옵션으로 통과 (없음)을 선택하고 다음을 클릭합니다.
Virtual Hosts 페이지에서 모든 가상 호스트가 선택되어 있는지 확인하고 Next를 클릭합니다.
Build 페이지에서 test 환경이 선택되어 있는지 확인하고 Build and Deploy를 클릭합니다.
요약 페이지에 새 API 프록시가 성공적으로 생성되어 테스트 환경에 배포되었다는 확인이 표시됩니다.
Mock-Target-API를 클릭하여 API 프록시의 개요 페이지를 표시합니다.

축하합니다. OpenAPI 사양에서 API 프록시를 만들었습니다. 다음으로, 이를 테스트하여 어떻게 작동하는지 확인합니다.

API 프록시 테스트

cURL 또는 웹브라우저를 사용하여 Mock-Target-API API를 테스트할 수 있습니다.

터미널 창에서 다음 cURL 명령어를 실행합니다. URL에서 조직 이름을 대체합니다.

curl http://<org_name>-test.apigee.net/mock-target-api

응답

다음과 같은 응답이 표시됩니다.

Hello, Guest!

수고하셨습니다! OpenAPI 사양에서 간단한 API 프록시를 빌드하고 테스트했습니다.

JSON 정책에 XML 추가

다음으로, OpenAPI 사양에서 API 프록시를 만들 때 자동으로 생성된 XML 응답 보기 조건부 흐름에 대한 JSON 정책에 XML을 추가합니다. 정책은 대상의 XML 응답을 JSON 응답으로 변환합니다.

먼저 API를 호출하여 정책을 추가한 후에 얻은 결과와 비교할 수 있습니다. 터미널 창에서 다음 cURL 명령어를 실행합니다. 대상 서비스의 /xml 리소스를 호출하면 기본적으로 XML의 간단한 블록이 반환됩니다. URL에서 조직 이름을 대체합니다.

curl http://<org_name>-test.apigee.net/mock-target-api/xml

응답

다음과 같은 응답이 표시됩니다.

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

이제 XML 응답을 JSON으로 변환하는 작업을 해보겠습니다. API 프록시에서 XML에서 JSON으로 변환 정책을 XML 응답 보기 조건부 흐름에 추가합니다.

Edge UI Mock-Target-API 개요 페이지의 오른쪽 상단에 있는 개발 탭을 클릭합니다.
왼쪽 탐색기 창의 프록시 엔드포인트 > 기본값에서 XML 응답 보기 조건부 흐름을 클릭합니다.
흐름의 응답에 해당하는 하단의 +단계 버튼을 클릭합니다.

단계 추가 대화상자가 열리고 추가할 수 있는 모든 정책이 분류된 목록이 표시됩니다.
미디에이션 카테고리로 스크롤하고 XML to JSON을 선택합니다.
표시 이름과 이름의 기본값을 그대로 둡니다.
Add를 클릭합니다. XML to JSON 정책이 응답에 적용됩니다.
저장을 클릭합니다.

정책을 추가했으므로 이제 cURL을 사용하여 API를 다시 호출합니다. 동일한 /xml 리소스를 여전히 호출하는 중입니다. 대상 서비스는 여전히 XML 블록을 반환하지만 이제 API 프록시의 정책이 응답을 JSON으로 변환합니다. 다음과 같이 호출합니다.

curl http://<org_name>-test.apigee.net/mock-target-api/xml

XML 응답은 JSON으로 변환됩니다.

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

축하합니다. 조건부 흐름에 추가된 정책 실행을 성공적으로 테스트했습니다.