API Gateway에 API 설명서 표시 - Amazon API Gateway
설명서 부분설명서 버전

API Gateway에 API 설명서 표시

API Gateway API 설명서는 API, 리소스, 메서드, 요청, 응답, 메시지 파라미터(즉 경로, 쿼리, 헤더)뿐 아니라 권한 부여자 및 모델을 포함하는 특정 API 엔터티와 연결된 개별 설명서 부분으로 구성됩니다.

API Gateway에서 설명서 부분은 DocumentationPart 리소스로 표시됩니다. API 설명서 전체는 DocumentationParts 컬렉션으로 표시됩니다.

API 문서화에는 API가 개선됨에 따라 DocumentationPart 인스턴스 생성, 인스턴스를 DocumentationParts 모음에 추가, 문서 부분의 버전을 관리하는 작업이 포함됩니다.

설명서 부분

DocumentationPart 리소스는 개별 API 엔터티에 적용 가능한 설명서 콘텐츠를 저장하는 JSON 객체입니다. properties 필드에는 설명서 콘텐츠가 키-값 페어의 맵으로 포함됩니다. location 속성은 연관된 API 엔터티를 식별합니다.

콘텐츠 맵의 형태는 API 개발자가 결정합니다. 키-값 페어의 값은 문자열, 숫자, 부울, 객체 또는 어레이일 수 있습니다. location 객체의 형태는 대상 엔터티 유형에 따라 결정됩니다.

DocumentationPart 리소스는 콘텐츠 상속을 지원합니다. API 엔터티의 설명서 콘텐츠는 해당 API 엔터티의 하위에 적용됩니다. 하위 엔터티 및 콘텐츠 상속의 정의에 대한 자세한 내용은 더 일반적인 사양의 API 엔터티에서 콘텐츠 상속 단원을 참조하십시오.

설명서 부분의 위치

DocumentationPart 인스턴스의 location 속성은 연결된 콘텐츠가 적용되는 API 엔터티를 식별합니다. API 엔터티는 API Gateway REST API 리소스(예: RestApi, Resource, Method, MethodResponse, Authorizer 또는 Model)일 수 있습니다. 엔터티는 URL 경로 파라미터, 쿼리 문자열 파라미터, 요청 또는 응답 헤더 파라미터, 요청 또는 응답 본문 또는 응답 상태 코드와 같은 메시지 파라미터일 수도 있습니다.

API 엔터티를 지정하려면 location 객체의 type 속성을 API, AUTHORIZER, MODEL, RESOURCE, METHOD, PATH_PARAMETER, QUERY_PARAMETER, REQUEST_HEADER, REQUEST_BODY, RESPONSE, RESPONSE_HEADER 또는 RESPONSE_BODY 중 하나로 설정합니다.

API 엔터티의 type에 따라 method, name, path 및 statusCode를 포함한 기타 location 속성을 지정할 수 있습니다. 이러한 속성이 모두 특정 API 엔터티에 유효하지는 않습니다. 예를 들어 type, path, name 및 statusCode는 RESPONSE 엔터티의 유효한 속성이고, type 및 path만 RESOURCE 엔터티의 유효한 위치 속성입니다. 주어진 API 엔터티에 대해 location의 DocumentationPart에 잘못된 필드를 포함시키는 것은 오류입니다.

모든 유효한 location 필드가 필요하지는 않습니다. 예를 들어, type은 모든 API 엔터티의 유효한 필수 location 필드입니다. 그러나 method, path 및 statusCode는 유효하지만 RESPONSE 엔터티의 필수 속성은 아닙니다. 명시적으로 지정되지 않으면 유효한 location 필드는 기본값을 사용합니다. 기본 path 값은 /, 즉 API의 루트 리소스입니다. method의 기본값 또는 statusCode는 *입니다. 이는 각각 모든 메서드 또는 상태 코드 값을 의미합니다.

설명서 부분의 콘텐츠

properties 값은 JSON 문자열로 인코딩됩니다. properties 값에는 설명서 요구사항을 충족하기 위해 선택한 정보가 포함되어 있습니다. 예를 들어, 다음은 유효한 콘텐츠 맵입니다.

{
  "info": {
    "description": "My first API with Amazon API Gateway."
  },
  "x-custom-info" : "My custom info, recognized by OpenAPI.",
  "my-info" : "My custom info not recognized by OpenAPI."
}

API Gateway는 유효한 JSON 문자열을 콘텐츠 맵으로 허용하지만, 콘텐츠 속성은 OpenAPI에서 인식할 수 있는 범주와 인식할 수 없는 범주라는 두 가지 범주로 처리됩니다. 이전 예에서 info, description 및 x-custom-info는 OpenAPI에서 표준 OpenAPI 객체, 속성 또는 확장으로 인식합니다. 반대로 my-info는 OpenAPI 사양을 준수하지 않습니다. API Gateway는 OpenAPI 호환 콘텐츠 속성을 연결된 DocumentationPart 인스턴스의 API 엔터티 정의로 전파합니다. API Gateway는 비호환 콘텐츠 속성을 API 엔터티 정의로 전파하지 않습니다.

또 다른 예로, 여기에 DocumentationPart 엔터티를 대상으로 하는 Resource가 있습니다.

{
    "location" : {
        "type" : "RESOURCE",
        "path": "/pets"
    },
    "properties" : {
        "summary" : "The /pets resource represents a collection of pets in PetStore.",
        "description": "... a child resource under the root...",
    }
}

여기서 type 및 path는 모두 RESOURCE 유형의 대상을 식별하는 데 유효한 필드입니다. 루트 리소스(/)의 경우, path 필드를 생략할 수 있습니다.

{
    "location" : {
        "type" : "RESOURCE"
    },
    "properties" : {
        "description" : "The root resource with the default path specification."
    }
}

이는 다음 DocumentationPart 인스턴스와 동일합니다.

{
    "location" : {
        "type" : "RESOURCE",
        "path": "/"
    },
    "properties" : {
        "description" : "The root resource with an explicit path specification"
    }
}

더 일반적인 사양의 API 엔터티에서 콘텐츠 상속

선택적 location 필드의 기본값은 API 엔터티의 패턴이 있는 설명을 제공합니다. location 객체의 기본값을 사용하면 이 properties 패턴 유형의 DocumentationPart 인스턴스에 location 맵의 일반적인 설명을 추가할 수 있습니다. 특정 엔터티에 연결된 DocumentationPart 인스턴스가 아직 없으면, API Gateway는 일반 API 엔터티의 location에서 적용 가능한 OpenAPI 설명서 속성을 추출하고 일반 location 패턴과 일치하거나 정확한 값과 일치하는 DocumentationPart 필드를 사용하여 특정 API 엔터티에 해당 속성을 주입합니다. 이 동작은 더 일반적인 사양의 API 엔터티에서 콘텐츠 상속이라고도 합니다.

콘텐츠 상속은 특정 API 개체 유형에는 적용되지 않습니다. 자세한 내용은 아래 표를 참조하십시오.

API 엔터티가 둘 이상의 DocumentationPart 위치 패턴과 일치할 때 엔터티는 설명서 부분을 우선 순위가 가장 높은 위치 필드로 상속합니다. 우선 순위는 path > statusCode입니다. path 필드와 일치시키기 위해 API Gateway는 가장 구체적인 경로 값이 있는 엔터티를 선택합니다. 다음 표에는 몇 가지 예가 나와 있습니다.

케이스 path statusCode name 설명
1 /pets * id

이 위치 패턴과 관련된 설명서는 위치 패턴과 일치하는 엔터티에 상속됩니다.
2 /pets 200 id

케이스 2가 케이스 1보다 더 구체적이기 때문에 이 위치 패턴과 관련된 문서는 케이스 1과 케이스 2가 일치할 때 위치 패턴과 일치하는 엔터티에 상속됩니다.
3 /pets/petId * id

케이스 3이 케이스 2보다 우선 순위가 높고 케이스 1보다 구체적이기 때문에 케이스 1, 2 및 3이 일치할 때 이 위치 패턴과 관련된 문서가 위치 패턴과 일치하는 엔터티에 상속됩니다.

보다 일반적인 DocumentationPart 인스턴스와 보다 구체적인 인스턴스를 대조하는 또 다른 예가 있습니다. 재정의되지 않는 한 다음과 같은 "Invalid request error"의 일반적인 오류 메시지가 400 오류 응답의 OpenAPI 정의에 삽입됩니다.

{
    "location" : {
        "type" : "RESPONSE",
        "statusCode": "400"
    },
    "properties" : {
        "description" : "Invalid request error."
    }"
}

다음 덮어쓰기를 사용하면 400 리소스의 모든 메서드에 대한 /pets 응답에 "Invalid petId specified"가 대신 설명됩니다.

{
    "location" : {
        "type" : "RESPONSE",
        "path": "/pets",
        "statusCode": "400"
    },
    "properties" : "{
        "description" : "Invalid petId specified."
    }"
}

DocumentationPart의 유효한 위치 필드

다음 표는 지정된 유형의 API 엔터티와 연결된 DocumentationPart 리소스의 적용 가능한 기본값과 유효 및 필수 필드를 보여줍니다.

API 엔터티 유효한 위치 필드 필수 위치 필드 기본 필드 값 상속 가능한 콘텐츠
API 
{
    "location": {
        "type": "API" 
    }, 
    ... 
}
 type 해당 사항 없음 아니요
리소스 
{ 
    "location": { 
        "type": "RESOURCE", 
        "path": "resource_path" 
    }, 
    ... 
}
 type path의 기본값은 /입니다. 아니요
방법 
{ 
    "location": { 
        "type": "METHOD", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}
 type path 및 method의 기본값은 각각 / 및 *입니다. 예, 접두사로 path를 매칭하고 모든 값의 method를 매칭합니다.
쿼리 파라미터 
{ 
    "location": { 
        "type": "QUERY_PARAMETER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "query_parameter_name" 
    }, 
    ... 
}
 type path 및 method의 기본값은 각각 / 및 *입니다. 예, 접두사로 path를 매칭하고 정확한 값으로 method를 매칭합니다.
요청 본문 
{ 
    "location": { 
        "type": "REQUEST_BODY", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}
 type path 및 method의 기본값은 각각 / 및 *입니다. 예, 접두사로 path를 매칭하고 정확한 값으로 method를 매칭합니다.
요청 헤더 파라미터 
{ 
    "location": { 
        "type": "REQUEST_HEADER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "header_name" 
    }, 
    ... 
}
 type, name path 및 method의 기본값은 각각 / 및 *입니다. 예, 접두사로 path를 매칭하고 정확한 값으로 method를 매칭합니다.
요청 경로 파라미터 
{ 
    "location": { 
        "type": "PATH_PARAMETER", 
        "path": "resource/{path_parameter_name}", 
        "method": "HTTP_verb",
        "name": "path_parameter_name" 
    }, 
    ... 
}
 type, name path 및 method의 기본값은 각각 / 및 *입니다. 예, 접두사로 path를 매칭하고 정확한 값으로 method를 매칭합니다.
응답 
{ 
    "location": { 
        "type": "RESPONSE", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}
 type path, method 및 statusCode의 기본값은 각각 /, * 및 *입니다. 예, 접두사로 path를 매칭하고 정확한 값으로 method 및 statusCode를 매칭합니다.
응답 헤더 
{ 
    "location": { 
        "type": "RESPONSE_HEADER", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code", 
        "name": "header_name" 
    }, 
    ... 
}
 type, name path, method 및 statusCode의 기본값은 각각 /, * 및 *입니다. 예, 접두사로 path를 매칭하고 정확한 값으로 method 및 statusCode를 매칭합니다.
응답 본문 
{ 
    "location": { 
        "type": "RESPONSE_BODY", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}
 type path, method 및 statusCode의 기본값은 각각 /, * 및 *입니다. 예, 접두사로 path를 매칭하고 정확한 값으로 method 및 statusCode를 매칭합니다.
권한 부여자 
{ 
    "location": { 
        "type": "AUTHORIZER", 
        "name": "authorizer_name" 
    }, 
    ... 
}
 type 해당 사항 없음 아니요
모델 
{ 
    "location": { 
        "type": "MODEL", 
        "name": "model_name" 
    }, 
    ... 
}
 type 해당 사항 없음 아니요

설명서 버전

설명서 버전은 API의 DocumentationParts 컬렉션에 대한 스냅샷이며 버전 식별자로 태그 지정됩니다. API의 설명서를 게시하려면 설명서 버전을 만들고 이를 API 단계와 연결하고 API 설명서의 해당 단계별 버전을 외부 OpenAPI 파일로 내보내는 작업이 필요합니다. API Gateway에서 설명서 스냅샷은 DocumentationVersion 리소스로 표시됩니다.

API를 업데이트하면 새 버전의 API가 만들어집니다. API Gateway에서는 DocumentationVersions 컬렉션을 사용하여 모든 설명서 버전을 유지 관리합니다.