API Gateway 콘솔을 사용하여 API 문서화 - Amazon API Gateway
API 엔터티 문서화RESOURCE 엔터티 문서화METHOD 엔터티 문서화QUERY_PARAMETER 엔터티 문서화PATH_PARAMETER 엔터티 문서화REQUEST_HEADER 엔터티 문서화 REQUEST_BODY 엔터티 문서화RESPONSE 엔터티 문서화RESPONSE_HEADER 엔터티 문서화RESPONSE_BODY 엔터티 문서화MODEL 엔터티 문서화AUTHORIZER 엔터티 문서화

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

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

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

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

API 엔터티 문서화

API 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

  1. 기본 탐색 창에서 설명서를 선택한 다음 설명서 부분 생성을 선택합니다.

  2. 설명서 유형에서 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 객체를 자동으로 문자열화합니다.

  3. 설명서 부분 생성을 선택합니다.

리소스 창에서 API 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

  1. 기본 탐색 창에서 리소스를 선택합니다.

  2. API 작업 메뉴를 선택한 다음 API 설명서 업데이트를 선택합니다.

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

기존 설명서 부분을 편집하려면 다음을 수행합니다.

  1. 설명서 창에서 리소스 및 메서드 탭을 선택합니다.

  2. API 이름을 선택한 다음 API 카드에서 편집을 선택합니다.

RESOURCE 엔터티 문서화

RESOURCE 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

  1. 기본 탐색 창에서 설명서를 선택한 다음 설명서 부분 생성을 선택합니다.

  2. 설명서 유형에서 리소스를 선택합니다.

  3. 경로에 경로를 입력합니다.

  4. 텍스트 편집기에서 설명을 입력합니다. 예를 들면 다음과 같습니다.

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

  5. 설명서 부분 생성을 선택합니다. 목록에 없는 리소스에 대한 설명서를 생성할 수 있습니다.

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

리소스 창에서 RESOURCE 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

  1. 기본 탐색 창에서 리소스를 선택합니다.

  2. 리소스를 선택한 다음 설명서 업데이트를 선택합니다.

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

기존 설명서 부분을 편집하려면 다음을 수행합니다.

  1. 설명서 창에서 리소스 및 메서드 탭을 선택합니다.

  2. 설명서 부분이 포함된 리소스를 선택한 다음 편집을 선택합니다.

METHOD 엔터티 문서화

METHOD 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

  1. 기본 탐색 창에서 설명서를 선택한 다음 설명서 부분 생성을 선택합니다.

  2. 설명서 유형에서 메서드를 선택합니다.

  3. 경로에 경로를 입력합니다.

  4. 메서드에서 HTTP 동사를 선택합니다.

  5. 텍스트 편집기에서 설명을 입력합니다. 예를 들면 다음과 같습니다.

    {
  "tags" : [ "pets" ],
  "summary" : "List all pets"
}

  6. 설명서 부분 생성을 선택합니다. 목록에 없는 메서드에 대한 설명서를 생성할 수 있습니다.

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

리소스 창에서 METHOD 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

  1. 기본 탐색 창에서 리소스를 선택합니다.

  2. 메서드를 선택한 다음 설명서 업데이트를 선택합니다.

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

기존 설명서 부분을 편집하려면 다음을 수행합니다.

  1. 설명서 창에서 리소스 및 메서드 탭을 선택합니다.

  2. 메서드를 선택하거나 메서드가 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다.

  3. 편집을 선택합니다.

QUERY_PARAMETER 엔터티 문서화

QUERY_PARAMETER 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

  1. 기본 탐색 창에서 설명서를 선택한 다음 설명서 부분 생성을 선택합니다.

  2. 설명서 유형에서 쿼리 파라미터를 선택합니다.

  3. 경로에 경로를 입력합니다.

  4. 메서드에서 HTTP 동사를 선택합니다.

  5. 이름에 이름을 입력합니다.

  6. 텍스트 편집기에서 설명을 입력합니다.

  7. 설명서 부분 생성을 선택합니다. 목록에 없는 쿼리 파라미터에 대한 설명서를 생성할 수 있습니다.

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

기존 설명서 부분을 편집하려면 다음을 수행합니다.

  1. 설명서 창에서 리소스 및 메서드 탭을 선택합니다.

  2. 쿼리 파라미터를 선택하거나 쿼리 파라미터가 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다.

  3. 편집을 선택합니다.

PATH_PARAMETER 엔터티 문서화

PATH_PARAMETER 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

  1. 기본 탐색 창에서 설명서를 선택한 다음 설명서 부분 생성을 선택합니다.

  2. 설명서 유형에서 경로 파라미터를 선택합니다.

  3. 경로에 경로를 입력합니다.

  4. 메서드에서 HTTP 동사를 선택합니다.

  5. 이름에 이름을 입력합니다.

  6. 텍스트 편집기에서 설명을 입력합니다.

  7. 설명서 부분 생성을 선택합니다. 목록에 없는 경로 파라미터에 대한 설명서를 생성할 수 있습니다.

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

기존 설명서 부분을 편집하려면 다음을 수행합니다.

  1. 설명서 창에서 리소스 및 메서드 탭을 선택합니다.

  2. 경로 파라미터를 선택하거나 경로 파라미터가 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다.

  3. 편집을 선택합니다.

REQUEST_HEADER 엔터티 문서화

REQUEST_HEADER 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

  1. 기본 탐색 창에서 설명서를 선택한 다음 설명서 부분 생성을 선택합니다.

  2. 설명서 유형에서 요청 헤더를 선택합니다.

  3. 경로에 요청 헤더의 경로를 입력합니다.

  4. 메서드에서 HTTP 동사를 선택합니다.

  5. 이름에 이름을 입력합니다.

  6. 텍스트 편집기에서 설명을 입력합니다.

  7. 설명서 부분 생성을 선택합니다. 목록에 없는 요청 헤더에 대한 설명서를 생성할 수 있습니다.

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

기존 설명서 부분을 편집하려면 다음을 수행합니다.

  1. 설명서 창에서 리소스 및 메서드 탭을 선택합니다.

  2. 요청 헤더를 선택하거나 요청 헤더가 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다.

  3. 편집을 선택합니다.

REQUEST_BODY 엔터티 문서화

REQUEST_BODY 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

  1. 기본 탐색 창에서 설명서를 선택한 다음 설명서 부분 생성을 선택합니다.

  2. 설명서 유형에서 요청 본문을 선택합니다.

  3. 경로에 요청 본문의 경로를 입력합니다.

  4. 메서드에서 HTTP 동사를 선택합니다.

  5. 텍스트 편집기에서 설명을 입력합니다.

  6. 설명서 부분 생성을 선택합니다. 목록에 없는 요청 본문에 대한 설명서를 생성할 수 있습니다.

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

기존 설명서 부분을 편집하려면 다음을 수행합니다.

  1. 설명서 창에서 리소스 및 메서드 탭을 선택합니다.

  2. 요청 본문을 선택하거나 요청 본문이 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다.

  3. 편집을 선택합니다.

RESPONSE 엔터티 문서화

RESPONSE 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

  1. 기본 탐색 창에서 설명서를 선택한 다음 설명서 부분 생성을 선택합니다.

  2. 설명서 유형에서 응답(상태 코드)을 선택합니다.

  3. 경로에 응답의 경로를 입력합니다.

  4. 메서드에서 HTTP 동사를 선택합니다.

  5. 상태 코드에 HTTP 상태 코드를 입력합니다.

  6. 텍스트 편집기에서 설명을 입력합니다.

  7. 설명서 부분 생성을 선택합니다. 목록에 없는 응답 상태 코드에 대한 설명서를 생성할 수 있습니다.

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

기존 설명서 부분을 편집하려면 다음을 수행합니다.

  1. 설명서 창에서 리소스 및 메서드 탭을 선택합니다.

  2. 응답 상태 코드를 선택하거나 응답 상태 코드가 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다.

  3. 편집을 선택합니다.

RESPONSE_HEADER 엔터티 문서화

RESPONSE_HEADER 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

  1. 기본 탐색 창에서 설명서를 선택한 다음 설명서 부분 생성을 선택합니다.

  2. 설명서 유형에서 응답 헤더를 선택합니다.

  3. 경로에 응답 헤더의 경로를 입력합니다.

  4. 메서드에서 HTTP 동사를 선택합니다.

  5. 상태 코드에 HTTP 상태 코드를 입력합니다.

  6. 텍스트 편집기에서 설명을 입력합니다.

  7. 설명서 부분 생성을 선택합니다. 목록에 없는 응답 헤더에 대한 설명서를 생성할 수 있습니다.

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

기존 설명서 부분을 편집하려면 다음을 수행합니다.

  1. 설명서 창에서 리소스 및 메서드 탭을 선택합니다.

  2. 응답 헤더를 선택하거나 응답 헤더가 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다.

  3. 편집을 선택합니다.

RESPONSE_BODY 엔터티 문서화

RESPONSE_BODY 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

  1. 기본 탐색 창에서 설명서를 선택한 다음 설명서 부분 생성을 선택합니다.

  2. 설명서 유형에서 응답 본문을 선택합니다.

  3. 경로에 응답 본문의 경로를 입력합니다.

  4. 메서드에서 HTTP 동사를 선택합니다.

  5. 상태 코드에 HTTP 상태 코드를 입력합니다.

  6. 텍스트 편집기에서 설명을 입력합니다.

  7. 설명서 부분 생성을 선택합니다. 목록에 없는 응답 본문에 대한 설명서를 생성할 수 있습니다.

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

기존 설명서 부분을 편집하려면 다음을 수행합니다.

  1. 설명서 창에서 리소스 및 메서드 탭을 선택합니다.

  2. 응답 본문을 선택하거나 응답 본문이 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다.

  3. 편집을 선택합니다.

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'의 속성이 원본 스키마의 값을 재정의합니다.

MODEL 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

  1. 기본 탐색 창에서 설명서를 선택한 다음 설명서 부분 생성을 선택합니다.

  2. 설명서 유형에서 모델을 선택합니다.

  3. 이름에 모델의 이름을 입력합니다.

  4. 텍스트 편집기에서 설명을 입력합니다.

  5. 설명서 부분 생성을 선택합니다. 목록에 없는 모델에 대한 설명서를 생성할 수 있습니다.

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

모델 창에서 MODEL 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

  1. 기본 탐색 창에서 모델을 선택합니다.

  2. 모델을 선택한 다음 설명서 업데이트를 선택합니다.

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

기존 설명서 부분을 편집하려면 다음을 수행합니다.

  1. 설명서 창에서 모델 탭을 선택합니다.

  2. 검색 창을 사용하거나 모델을 선택한 다음 편집을 선택합니다.

AUTHORIZER 엔터티 문서화

AUTHORIZER 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

  1. 기본 탐색 창에서 설명서를 선택한 다음 설명서 부분 생성을 선택합니다.

  2. 설명서 유형에서 권한 부여자를 선택합니다.

  3. 이름에 권한 부여자 이름을 입력합니다.

  4. 텍스트 편집기에서 설명을 입력합니다. 권한 부여자에 대한 유효한 location 필드의 값을 지정합니다.

  5. 설명서 부분 생성을 선택합니다. 목록에 없는 권한 부여자에 대한 설명서를 생성할 수 있습니다.

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

기존 설명서 부분을 편집하려면 다음을 수행합니다.

  1. 설명서 창에서 권한 부여자 탭을 선택합니다.

  2. 검색 창을 사용하거나 권한 부여자를 선택한 다음 편집을 선택합니다.