API Gateway REST API를 사용하여 API 설명서 게시 - Amazon API Gateway
설명서 스냅샷을 생성하여 API 단계와 연결설명서 스냅샷 만들기설명서 스냅샷 업데이트설명서 스냅샷 가져오기설명서 스냅샷을 API 단계와 연결단계와 연결된 설명서 스냅샷 다운로드

API Gateway REST API를 사용하여 API 설명서 게시

API에 대한 설명서를 게시하려면 설명서 스냅샷을 생성 또는 업데이트하거나 가져온 다음, 설명서 스냅샷을 API 단계와 연결합니다. 설명서 스냅샷을 생성할 때 이를 동시에 API 단계와 연결할 수도 있습니다.

설명서 스냅샷을 생성하여 API 단계와 연결

API의 설명서 부분의 스냅샷을 생성하여 동시에 API 단계와 연결하려면 다음 POST 요청을 제출하십시오.

POST /restapis/restapi_id/documentation/versions HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret

{
    "documentationVersion" : "1.0.0",
    "stageName": "prod",
    "description" : "My API Documentation v1.0.0"
}

성공하면 해당 작업은 페이로드로 새로 생성된 200 OK 인스턴스를 포함하는 DocumentationVersion 응답을 반환합니다.

또는 API 단계와 먼저 연결하지 않고 설명서 스냅샷을 생성한 다음, restapi:update를 호출하여 스냅샷을 지정된 API 단계와 연결할 수 있습니다. 기존 설명서 스냅샷을 업데이트 또는 쿼리한 다음, 단계 연결을 업데이트할 수도 있습니다. 다음 4개 단원에서 단계를 보여드립니다.

설명서 스냅샷 만들기

API 설명서 부분의 스냅샷을 생성하려면 새 DocumentationVersion 리소스를 생성하여 API의 DocumentationVersions 컬렉션에 추가합니다.

POST /restapis/restapi_id/documentation/versions HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret

{
    "documentationVersion" : "1.0.0",
    "description" : "My API Documentation v1.0.0"
}

성공하면 해당 작업은 페이로드로 새로 생성된 200 OK 인스턴스를 포함하는 DocumentationVersion 응답을 반환합니다.

설명서 스냅샷 업데이트

해당 DocumentationVersion 리소스의 description 속성을 수정하는 방법으로만 설명서 스냅샷을 업데이트할 수 있습니다. 다음 예에서는 version 버전 ID(예: 1.0.0)로 식별된 설명서 스냅샷의 설명을 업데이트하는 방법을 보여줍니다.

PATCH /restapis/restapi_id/documentation/versions/version HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret

{
    "patchOperations": [{
        "op": "replace",
        "path": "/description",
        "value": "My API for testing purposes."
    }]
}

성공하면 해당 작업은 페이로드로 업데이트된 200 OK 인스턴스를 포함하는 DocumentationVersion 응답을 반환합니다.

설명서 스냅샷 가져오기

설명서 스냅샷을 가져오려면 지정된 DocumentationVersion 리소스에 대해 GET 요청을 제출합니다. 다음 예에서는 지정된 버전 ID 1.0.0의 설명서 스냅샷을 가져오는 방법을 보여줍니다.

GET /restapis/<restapi_id>/documentation/versions/1.0.0 HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret

설명서 스냅샷을 API 단계와 연결

API 설명서를 게시하려면 설명서 스냅샷을 API 단계와 연결합니다. 설명서 버전을 단계와 연결하기 전에 API 단계를 이미 생성해야 합니다.

API Gateway REST API를 사용하여 설명서 스냅샷을 API 단계와 연결하려면 stage:update 작업을 호출하여 stage.documentationVersion 속성에서 원하는 설명서 버전을 설정합니다.

PATCH /restapis/RESTAPI_ID/stages/STAGE_NAME
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret

{
    "patchOperations": [{
        "op": "replace",
        "path": "/documentationVersion",
        "value": "VERSION_IDENTIFIER"
    }]
}

단계와 연결된 설명서 스냅샷 다운로드

설명서 부분의 한 버전이 단계와 연결된 후, API Gateway 콘솔, API Gateway REST API, SDK 중 하나 또는 API Gateway용 AWS CLI를 사용하여 API 엔터티 정의와 함께 설명서 부분을 외부 파일로 내보낼 수 있습니다. 이 프로세스는 API를 내보내는 프로세스와 동일합니다. 내보낸 파일 형식은 JSON 또는 YAML일 수 있습니다.

또한 API Gateway REST API를 사용하여 API 설명서 부분, API 통합 및 권한 부여자를 API 내보내기에 포함하도록 extension=documentation,integrations,authorizers 쿼리 파라미터를 명시적으로 설정할 수도 있습니다. 기본적으로 API를 내보낼 때 설명서 부분은 포함되지만 통합 및 권한 부여자는 제외됩니다. API 내보내기의 기본 출력은 설명서 배포에 적합합니다.

API Gateway REST API를 사용하여 API 설명서를 외부 JSON OpenAPI 파일로 내보내려면 다음 GET 요청을 제출합니다.

GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=documentation HTTP/1.1
Accept: application/json
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret

여기서 x-amazon-apigateway-documentation 객체에는 설명서 부분이 포함되고 API 엔터티 정의에는 OpenAPI에서 지원하는 설명서 속성이 포함됩니다. 출력에는 통합 또는 Lambda 권한 부여자(이전에는 사용자 지정 권한 부여자라고 함)의 세부 정보가 포함되지 않습니다. 두 가지 세부 정보를 모두 포함하려면 extensions=integrations,authorizers,documentation을 설정하십시오. 통합 세부 정보는 포함하지만 권한 부여자 세부 정보는 포함하지 않으려면 extensions=integrations,documentation을 설정하십시오.

결과를 JSON 파일로 출력하려면 요청에 Accept:application/json 헤더를 설정해야 합니다. YAML 출력을 생성하려면 요청 헤더를 Accept:application/yaml로 변경하십시오.

예를 들어, 루트 리소스(GET)에서 간단한 / 메서드를 표시하는 API를 볼 수 있습니다. 이 API에는 OpenAPI 정의 파일에 정의된 API 엔터티가 네 개 있습니다. 각각 API, MODEL, METHOD 및 RESPONSE 유형에 해당하는 엔터티입니다. 설명서 부분이 각 API, METHOD 및 RESPONSE 엔터티에 추가되었습니다. 이전 설명서 내보내기 명령을 호출하면 설명서 부분이 x-amazon-apigateway-documentation 객체에 표준 OpenAPI 파일에 대한 확장으로 나열되는 다음과 같은 출력이 표시됩니다.

OpenAPI 3.0
{
   "openapi": "3.0.0",
   "info": {
      "description": "API info description",
      "version": "2016-11-22T22:39:14Z",
      "title": "doc",
      "x-bar": "API info x-bar"
   },
   "paths": {
      "/": {
         "get": {
            "description": "Method description.",
            "responses": {
               "200": {
                  "description": "200 response",
                  "content": {
                     "application/json": {
                        "schema": {
                           "$ref": "#/components/schemas/Empty"
                        }
                     }
                  }
               }
            },
            "x-example": "x- Method example"
         },
         "x-bar": "resource x-bar"
      }
   },
   "x-amazon-apigateway-documentation": {
      "version": "1.0.0",
      "createdDate": "2016-11-22T22:41:40Z",
      "documentationParts": [
         {
            "location": {
               "type": "API"
            },
            "properties": {
               "description": "API description",
               "foo": "API foo",
               "x-bar": "API x-bar",
               "info": {
                  "description": "API info description",
                  "version": "API info version",
                  "foo": "API info foo",
                  "x-bar": "API info x-bar"
               }
            }
         },
         {
            "location": {
               "type": "METHOD",
               "method": "GET"
            },
            "properties": {
               "description": "Method description.",
               "x-example": "x- Method example",
               "foo": "Method foo",
               "info": {
                  "version": "method info version",
                  "description": "method info description",
                  "foo": "method info foo"
               }
            }
         },
         {
            "location": {
               "type": "RESOURCE"
            },
            "properties": {
               "description": "resource description",
               "foo": "resource foo",
               "x-bar": "resource x-bar",
               "info": {
                  "description": "resource info description",
                  "version": "resource info version",
                  "foo": "resource info foo",
                  "x-bar": "resource info x-bar"
               }
            }
         }
      ]
   },
   "x-bar": "API x-bar",
   "servers": [
      {
         "url": "https://rznaap68yi.execute-api.ap-southeast-1.amazonaws.com/{basePath}",
         "variables": {
            "basePath": {
              "default": "/test"
            }
         }
      }
   ],
   "components": {
      "schemas": {
         "Empty": {
            "type": "object",
            "title": "Empty Schema"
         }
      }
   }
}
OpenAPI 2.0
{
  "swagger" : "2.0",
  "info" : {
    "description" : "API info description",
    "version" : "2016-11-22T22:39:14Z",
    "title" : "doc",
    "x-bar" : "API info x-bar"
  },
  "host" : "rznaap68yi.execute-api.ap-southeast-1.amazonaws.com",
  "basePath" : "/test",
  "schemes" : [ "https" ],
  "paths" : {
    "/" : {
      "get" : {
        "description" : "Method description.",
        "produces" : [ "application/json" ],
        "responses" : {
          "200" : {
            "description" : "200 response",
            "schema" : {
              "$ref" : "#/definitions/Empty"
            }
          }
        },
        "x-example" : "x- Method example"
      },
      "x-bar" : "resource x-bar"
    }
  },
  "definitions" : {
    "Empty" : {
      "type" : "object",
      "title" : "Empty Schema"
    }
  },
  "x-amazon-apigateway-documentation" : {
    "version" : "1.0.0",
    "createdDate" : "2016-11-22T22:41:40Z",
    "documentationParts" : [ {
      "location" : {
        "type" : "API"
      },
      "properties" : {
        "description" : "API description",
        "foo" : "API foo",
        "x-bar" : "API x-bar",
        "info" : {
          "description" : "API info description",
          "version" : "API info version",
          "foo" : "API info foo",
          "x-bar" : "API info x-bar"
        }
      }
    }, {
      "location" : {
        "type" : "METHOD",
        "method" : "GET"
      },
      "properties" : {
        "description" : "Method description.",
        "x-example" : "x- Method example",
        "foo" : "Method foo",
        "info" : {
          "version" : "method info version",
          "description" : "method info description",
          "foo" : "method info foo"
        }
      }
    }, {
      "location" : {
        "type" : "RESOURCE"
      },
      "properties" : {
        "description" : "resource description",
        "foo" : "resource foo",
        "x-bar" : "resource x-bar",
        "info" : {
          "description" : "resource info description",
          "version" : "resource info version",
          "foo" : "resource info foo",
          "x-bar" : "resource info x-bar"
        }
      }
    } ]
  },
  "x-bar" : "API x-bar"
}

설명서 부분의 properties 맵에 정의된 OpenAPI 호환 속성의 경우 API Gateway는 연결된 API 엔터티 정의에 속성을 삽입합니다. x-something의 속성은 표준 OpenAPI 확장입니다. 이 확장은 API 엔터티 정의에 전파됩니다. 예를 들어, x-example 메서드에 대한 GET 속성을 참조하십시오. foo 같은 속성은 OpenAPI 사양의 일부가 아니고 연결된 API 엔터티 정의에 삽입되지 않습니다.

설명서 렌더링 도구(예: OpenAPI UI)가 API 엔터티 정의를 구문 분석하여 설명서 속성을 추출할 경우, properties 인스턴스의 Swagger 비호환 DocumentationPart 속성은 도구에서 사용할 수 없습니다. 그러나 설명서 렌더링 도구에서 x-amazon-apigateway-documentation 객체를 구문 분석하여 콘텐츠를 가져오거나 도구에서 restapi:documentation-parts 및 documenationpart:by-id를 호출하여 API Gateway에서 설명서 부분을 가져올 경우, 모든 설명서 속성을 도구에 사용하여 표시할 수 있습니다.

통합 세부 정보를 포함하는 API 엔터티가 있는 설명서를 JSON OpenAPI 파일로 내보내려면 다음 GET 요청을 제출하십시오.

GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,documentation HTTP/1.1
Accept: application/json
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret

통합 및 권한 부여자 세부 정보를 포함하는 API 엔터티가 있는 설명서를 YAML OpenAPI 파일로 내보내려면 다음 GET 요청을 제출하십시오.

GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,authorizers,documentation HTTP/1.1
Accept: application/yaml
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret

API Gateway 콘솔을 사용하여 API의 게시된 설명서를 내보내거나 다운로드하려면 API Gateway 콘솔을 사용하여 REST API 내보내기의 지침을 따릅니다.