API Gateway 콘솔을 사용하여 API 문서화 - Amazon API Gateway

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

API Gateway 콘솔을 사용하여 API 문서화

이 단원에서는 API Gateway 콘솔을 사용하여 API의 설명서 부분을 생성하고 유지 관리하는 방법에 대해 설명합니다.

API의 설명서를 작성하고 편집하기 위한 전제 조건으로 API를 이미 작성했어야 합니다. 이 단원에서는 PetStore API를 예로 사용합니다. API Gateway 콘솔을 사용하여 API를 생성하려면 자습서: 예제를 가져와 REST API 생성의 지침을 따릅니다.

API 엔터티 문서화

API 엔터티의 설명서 부분을 추가하려면 PetStore API에서 리소스를 선택합니다. Actions → Edit API Documentation(작업 → API 편집 설명서) 메뉴 항목을 선택합니다.


                    API Gateway 콘솔에서 API 엔터티에 대한 설명서 편집

설명서 부분이 API용으로 생성되지 않은 경우, 설명서 부분의 properties 맵 편집기를 가져옵니다. 텍스트 편집기에 다음 properties 맵을 입력한 다음 저장을 선택하여 설명서 부분을 생성합니다.

{ "info": { "description": "Your first API Gateway API.", "contact": { "name": "John Doe", "email": "john.doe@api.com" } } }
참고

properties 맵을 JSON 문자열에 인코딩할 필요가 없습니다. API Gateway 콘솔은 JSON 객체를 자동으로 문자열화합니다.


                    API Gateway 콘솔에서 API 엔터티에 대한 설명서 속성 맵 편집

설명서 부분이 이미 생성된 경우에는 다음과 같이 properties 맵 뷰어를 먼저 가져옵니다.


                    API Gateway 콘솔에서 API 엔터티에 대한 설명서 속성 맵 보기

편집을 선택하면 앞에 표시된 것처럼 properties 맵 편집기가 나타납니다.

RESOURCE 엔터티 문서화

API의 루트 리소스에 대한 설명서 부분을 추가 또는 편집하려면 리소스 트리에서 /을 선택한 다음 작업 → 리소스 설명서 편집(Actions → Edit Resource Documentation) 메뉴 항목을 선택합니다.

이 엔터티에 대한 설명서 부분이 생성되지 않은 경우 설명서 창이 표시됩니다. 편집기에서 유효한 properties 맵을 입력합니다. 그런 다음 저장닫기를 선택합니다.

{ "description": "The PetStore's root resource." }

RESOURCE 엔터티에 대한 설명서 부분이 이미 정의된 경우 설명서 뷰어가 표시됩니다. 편집을 선택하여 설명서 편집기를 엽니다. 기존 properties 맵을 수정합니다. 저장을 선택한 다음 닫기를 선택합니다.

필요한 경우 이 단계를 반복하여 설명서 부분을 다른 RESOURCE 엔터티에 추가합니다.

METHOD 엔터티 문서화

루트 리소스의 GET 메서드를 예로 사용하여 METHOD 엔터티에 대한 설명서를 추가 또는 편집하려면 / 리소스에서 GET을 선택한 다음 작업 → 메서드 설명서 편집(Actions → Edit Method Documentation) 메뉴 항목을 선택합니다.

새로운 설명서 부분의 경우 설명서 창의 설명서 편집기에서 다음 properties 맵을 입력합니다. 그런 다음 저장닫기를 선택합니다.

{ "tags" : [ "pets" ], "description" : "PetStore HTML web page containing API usage information" }

기존 설명서의 경우 설명서 뷰어에서 편집을 선택합니다. 설명서 편집기에서 설명서 콘텐츠를 편집하고 저장을 선택합니다. 닫기를 선택합니다.

설명서 뷰어에서 설명서 부분을 삭제할 수도 있습니다.

필요한 경우 이 단계를 반복하여 설명서 부분을 다른 메서드에 추가합니다.

QUERY_PARAMETER 엔터티 문서화

GET /pets?type=...&page=... 메서드를 예로 사용하여 요청 쿼리 파라미터에 대한 설명서 부분을 추가 또는 편집하려면 리소스 트리의 /pets에서 GET을 선택합니다. 메서드 실행(Method Execution) 창에서 메서드 요청(Method Request)을 선택합니다. URL 쿼리 문자열 파라미터(URL Query String Parameters) 섹션을 확장합니다. 예를 들어 페이지(page) 쿼리 파라미터를 선택하고 책 아이콘을 선택하여 설명서 뷰어 또는 편집기를 엽니다.


                    API Gateway 콘솔에서 API 엔터티에 대한 설명서 편집

또는 기본 탐색 창의 PetStore API에서 설명서를 선택할 수 있습니다. 그런 다음 유형에서 Query Parameter를 선택합니다. PetStore 예 API의 경우 여기에서 pagetype 쿼리 파라미터에 대한 설명서 부분을 표시합니다.


                    API Gateway 콘솔에서 API 엔터티에 대한 설명서 편집

다른 메서드에 대해 정의된 쿼리 파라미터가 포함된 API의 경우 경로에 대해 해당하는 리소스의 path를 지정하고 방법에서 원하는 HTTP 메서드를 선택하거나 이름에서 쿼리 파라미터 이름을 입력하여 선택항목을 필터링할 수 있습니다.

예를 들어, page 쿼리 파라미터를 선택합니다. 편집을 선택하여 기존 설명서를 수정합니다. 저장을 선택하여 변경 사항을 저장합니다.

QUERY_PARAMETER 엔터티에 대한 새 설명서 부분을 추가하려면 설명서 부분 생성(Create Documentation Part)을 선택합니다. 유형에서 Query Parameter를 선택합니다. 경로에서 리소스 경로(예: /pets)를 입력합니다. 방법에서 HTTP 동사(예: GET)를 선택합니다. 텍스트 편집기에서 properties 설명을 입력합니다. 그런 다음 [Save]를 선택합니다.

필요한 경우 이 단계를 반복하여 설명서 부분을 다른 요청 쿼리 파라미터에 추가합니다.

PATH_PARAMETER 엔터티 문서화

경로 파라미터에 대한 설명서를 추가 또는 편집하려면 경로 파라미터에서 지정한 리소스에 있는 메서드의 메서드 요청(Method Request)으로 이동합니다. 경로 요청(Request Paths) 섹션을 확장합니다. 경로 파라미터에 대한 책 아이콘을 선택하여 설명서 뷰어 또는 편집기를 엽니다. 설명서 부분의 속성을 추가하거나 수정합니다.

또는 기본 탐색 창의 PetStore API에서 설명서를 선택합니다. 유형에서 Path Parameter를 선택합니다. 목록에서 경로 파라미터에 대한 편집을 선택합니다. 콘텐츠를 수정한 다음 저장을 선택합니다.

나열되지 않은 경로 파라미터에 대한 설명서를 추가하려면 설명서 부분 생성(Create Documentation Part)을 선택합니다. 유형에서 경로 파라미터(Path Parameter)를 선택합니다. 경로에서 리소스 경로를 설정하고, 방법에서 메서드를 선택한 다음, 이름에서 경로 파라미터 이름을 설정합니다. 설명서의 속성을 추가하고 저장을 선택합니다.

필요한 경우 이 단계를 반복하여 설명서 부분을 다른 경로 파라미터에 추가하거나 편집합니다.

REQUEST_HEADER 엔터티 문서화

요청 헤더의 설명서를 추가 또는 편집하려면 헤더 파라미터가 포함된 메서드의 메서드 요청(Method Request)으로 이동합니다. HTTP 요청 헤더(HTTP Request Headers) 섹션을 확장합니다. 헤더에 대한 책 아이콘을 선택하여 설명서 뷰어 또는 편집기를 엽니다. 설명서 부분의 속성을 추가하거나 수정합니다.

또는 기본 탐색 창의 API에서 설명서를 선택합니다. 그런 다음 유형에서 Request Header를 선택합니다. 나열된 요청 헤더에서 편집을 선택하여 설명서를 변경합니다. 나열되지 않은 요청 헤더에 대한 설명서를 추가하려면 설명서 부분 생성(Create Documentation Part)을 선택합니다. 유형에 대해 요청 헤더(Request Header)를 선택합니다. 경로에서 리소스 경로를 지정합니다. 방법에서 메서드를 선택합니다. 이름에서 헤더 이름을 입력합니다. 그런 다음 properties 맵을 추가 및 저장합니다.

필요한 경우 이 단계를 반복하여 설명서 부분을 다른 요청 헤더에 추가하거나 편집합니다.

REQUEST_BODY 엔터티 문서화

요청 본문에 대한 설명서를 추가 또는 편집하려면 메서드의 메서드 요청(Method Request)으로 이동합니다. 요청 본문(Request Body)에 대한 책 아이콘을 선택하여 설명서 뷰어를 연 다음 편집기를 엽니다. 설명서 부분의 속성을 추가하거나 수정합니다.

또는 기본 탐색 창의 API에서 설명서를 선택합니다. 그런 다음 유형에서 Request Body를 선택합니다. 나열된 요청 본문에서 편집을 선택하여 설명서를 변경합니다. 나열되지 않은 요청 본문에 대한 설명서를 추가하려면 설명서 부분 생성(Create Documentation Part)을 선택합니다. 유형에서 Request Body를 선택합니다. 경로에서 리소스 경로를 설정합니다. 방법에서 HTTP 동사를 선택합니다. 그런 다음 properties 맵을 추가 및 저장합니다.

필요한 경우 이 단계를 반복하여 설명서 부분을 다른 요청 본문에 추가하거나 편집합니다.

RESPONSE 엔터티 문서화

응답에 대한 설명서를 추가 또는 편집하려면 메서드의 Method Response(메서드 응답)으로 이동합니다. 메서드 응답(Method Response)에 대한 책 아이콘을 선택하여 설명서 뷰어를 연 다음 편집기를 엽니다. 설명서 부분의 속성을 추가하거나 수정합니다.


                    API Gateway 콘솔에서 RESPONSE 엔터티에 대한 설명서 편집

또는 기본 탐색 창의 API에서 설명서를 선택합니다. 그런 다음 유형에서 Response (status code)를 선택합니다. 지정된 HTTP 상태 코드의 나열된 응답에서 편집을 선택하여 설명서를 변경합니다. 나열되지 않은 응답 본문에 대한 설명서를 추가하려면 설명서 부분 생성(Create Documentation Part)을 선택합니다. 유형에서 응답(상태 코드)(Response (status code))를 선택합니다. 경로에서 리소스 경로를 설정합니다. 방법에서 HTTP 동사를 선택합니다. 상태 코드에 HTTP 상태 코드를 입력합니다. 그런 다음 설명서 부분 속성을 추가하고 저장합니다.

필요한 경우 이 단계를 반복하여 설명서 부분을 다른 응답에 추가하거나 편집합니다.

RESPONSE_HEADER 엔터티 문서화

응답 헤더에 대한 설명서를 추가 또는 편집하려면 메서드의 메서드 응답(Method Response)으로 이동합니다. 지정된 HTTP 상태의 응답 섹션을 확장합니다. StatusCode에 대한 응답 헤더)에서 응답 헤더에 대한 책 아이콘을 선택하여 설명서 뷰어를 연 다음 편집기를 엽니다. 설명서 부분의 속성을 추가하거나 수정합니다.

또는 기본 탐색 창의 API에서 설명서를 선택합니다. 그런 다음 유형에서 Response Header를 선택합니다. 나열된 응답 헤더에서 편집을 선택하여 설명서를 변경합니다. 나열되지 않은 응답 헤더에 대한 설명서를 추가하려면 설명서 부분 생성(Create Documentation Part)을 선택합니다. 유형에서 응답 헤더(Response Header_를 선택합니다. 경로에서 리소스 경로를 설정합니다. 방법에서 HTTP 동사를 선택합니다. 상태 코드에 HTTP 상태 코드를 입력합니다. 이름에서 응답 헤더 이름을 입력합니다. 그런 다음 설명서 부분 속성을 추가하고 저장합니다.

필요한 경우 이 단계를 반복하여 설명서 부분을 다른 응답 헤더에 추가하거나 편집합니다.

RESPONSE_BODY 엔터티 문서화

응답 본문에 대한 설명서를 추가 또는 편집하려면 메서드의 메서드 응답(Method Response)으로 이동합니다. 지정된 HTTP 상태의 응답 섹션을 확장합니다. StatusCode에 대한 응답 본문(​Response Body for StatusCode)에 대한 책 아이콘을 선택하여 설명서 뷰어를 연 다음 편집기를 엽니다. 설명서 부분의 속성을 추가하거나 수정합니다.

또는 기본 탐색 창의 API에서 설명서를 선택합니다. 그런 다음 유형에서 Response Body를 선택합니다. 나열된 응답 본문에서 편집을 선택하여 설명서를 변경합니다. 나열되지 않은 응답 본문에 대한 설명서를 추가하려면 설명서 부분 생성(Create Documentation Part)을 선택합니다. 유형에서 응답 본문(Response Body)을 선택합니다. 경로에서 리소스 경로를 설정합니다. 방법에서 HTTP 동사를 선택합니다. 상태 코드에 HTTP 상태 코드를 입력합니다. 그런 다음 설명서 부분 속성을 추가하고 저장합니다.

필요한 경우 이 단계를 반복하여 설명서 부분을 다른 응답 본문에 추가하거나 편집합니다.

MODEL 엔터티 문서화

MODEL 엔터티를 문서화하려면 해당 모델의 DocumentPart 인스턴스 및 각각의 properties를 생성하고 관리해야 합니다. 예를 들어, 기본적으로 모든 API와 함께 제공되는 Error 모델에는 다음과 같은 스키마 정의가 있습니다.

{ "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "Error Schema", "type" : "object", "properties" : { "message" : { "type" : "string" } } }

그리고 두 개의 DocumentationPart 인스턴스가 필요합니다. 하나는 Model용이고 다른 하나는 message 속성용입니다.

{ "location": { "type": "MODEL", "name": "Error" }, "properties": { "title": "Error Schema", "description": "A description of the Error model" } }

{ "location": { "type": "MODEL", "name": "Error.message" }, "properties": { "description": "An error message." } }

API를 내보낼 경우 DocumentationPart'의 속성이 원본 스키마의 값을 재정의합니다.

모델에 대한 설명서를 추가 또는 편집하려면 기본 탐색 창에서 API의 모델로 이동합니다. 나열된 모델의 이름에 대한 책 아이콘을 선택하여 설명서 뷰어를 연 다음 편집기를 엽니다. 설명서 부분의 속성을 추가하거나 수정합니다.

또는 기본 탐색 창의 API에서 설명서를 선택합니다. 그런 다음 유형에서 Model를 선택합니다. 나열된 모델에서 편집을 선택하여 설명서를 변경합니다. 나열되지 않은 모델에 대한 설명서를 추가하려면 설명서 부분 생성(Create Documentation Part)을 선택합니다. 유형에서 모델을 선택합니다. 이름에서 모델에 대한 이름을 제공합니다. 그런 다음 설명서 부분 속성을 추가하고 저장합니다.

필요한 경우 이 단계를 반복하여 설명서 부분을 다른 모델에 추가하거나 편집합니다.

AUTHORIZER 엔터티 문서화

권한 부여자에 대한 설명서를 추가 또는 편집하려면 기본 탐색 창에서 API의 권한 부여자로 이동합니다. 나열된 권한 부여자에 대한 책 아이콘을 선택하여 설명서 뷰어를 연 다음 편집기를 엽니다. 설명서 부분의 속성을 추가하거나 수정합니다.

또는 기본 탐색 창의 API에서 설명서를 선택합니다. 그런 다음 유형에서 Authorizer를 선택합니다. 나열된 권한 부여자에서 편집을 선택하여 설명서를 변경합니다. 나열되지 않은 권한 부여자에 대한 설명서를 추가하려면 설명서 부분 생성(Create Documentation Part)을 선택합니다. 유형에서 권한 부여자를 선택합니다. 이름에 권한 부여자에 대한 이름을 입력합니다. 그런 다음 설명서 부분 속성을 추가하고 저장합니다.

필요한 경우 이 단계를 반복하여 설명서 부분을 다른 권한 부여자에 추가하거나 편집합니다.

권한 부여자에 대한 설명서 부분을 추가하려면 설명서 부분 생성(Create Documentation Part)을 선택합니다. 유형에서 권한 부여자를 선택합니다. 권한 부여자에 대한 이름의 유효한 location 필드에 대한 값을 지정합니다.

properties 맵 편집기에서 설명서 콘텐츠를 추가 및 저장합니다.

필요한 경우 이 단계를 반복하여 설명서 부분을 다른 권한 부여자에 추가합니다.