API 설명서 가져오기

API 엔터티 정의 가져오기와 마찬가지로 외부 OpenAPI 파일에서 API Gateway의 API로 설명서 부분을 가져올 수 있습니다. 유효한 OpenAPI 정의 파일의 x-amazon-apigateway-documentation 객체 확장 내에서 가져올 설명서 부분을 지정합니다. 설명서를 가져와도 기존 API 엔터티 정의는 변경되지 않습니다.

새로 지정된 설명서 부분을 API Gateway의 기존 설명서 부분에 병합하거나 기존 설명서 부분을 덮어쓸 수 있습니다. MERGE 모드에서는 OpenAPI 파일에 정의된 새 설명서 부분이 API의 DocumentationParts 컬렉션에 추가됩니다. 가져온 DocumentationPart가 이미 있는 경우 두 개의 속성이 다르면 가져온 속성이 기존 속성을 대체합니다. 다른 기존 설명서 속성은 그대로 남아 있습니다. OVERWRITE 모드에서는 전체 DocumentationParts 컬렉션이 가져온 OpenAPI 정의 파일에 따라 대체됩니다.

API Gateway REST API를 사용하여 설명서 부분 가져오기

API Gateway REST API를 사용하여 API 설명서를 가져오려면 documentationpart:import 작업을 호출합니다. 다음 예에서는 API의 기존 설명서 부분을 단일 GET / 메서드로 덮어쓰고 성공하면 200 OK 응답을 반환하는 방법을 보여줍니다.

OpenAPI 3.0

PUT /restapis/<restapi_id>/documentation/parts&mode=overwrite&failonwarnings=true
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

{
   "openapi": "3.0.0",
   "info": {
      "description": "description",
      "version": "1",
      "title": "doc"
   },
   "paths": {
      "/": {
         "get": {
            "description": "Method description.",
            "responses": {
               "200": {
                  "description": "200 response",
                  "content": {
                     "application/json": {
                        "schema": {
                           "$ref": "#/components/schemas/Empty"
                        }
                     }
                  }
               }
            }
         }
      }
   },
   "x-amazon-apigateway-documentation": {
      "version": "1.0.3",
      "documentationParts": [
         {
            "location": {
               "type": "API"
            },
            "properties": {
               "description": "API description",
               "info": {
                  "description": "API info description 4",
                  "version": "API info version 3"
               }
            }
         },
         {
            "location": {
               "type": "METHOD",
               "method": "GET"
            },
            "properties": {
               "description": "Method description."
            }
         },
         {
            "location": {
               "type": "MODEL",
               "name": "Empty"
            },
            "properties": {
               "title": "Empty Schema"
            }
         },
         {
            "location": {
               "type": "RESPONSE",
               "method": "GET",
               "statusCode": "200"
            },
            "properties": {
               "description": "200 response"
            }
         }
      ]
   },
   "servers": [
      {
         "url": "/"
      }
   ],
   "components": {
      "schemas": {
         "Empty": {
            "type": "object",
            "title": "Empty Schema"
         }
      }
   }
}

OpenAPI 2.0

PUT /restapis/<restapi_id>/documentation/parts&mode=overwrite&failonwarnings=true
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

{
  "swagger": "2.0",
  "info": {
    "description": "description",
    "version": "1",
    "title": "doc"
  },
  "host": "",
  "basePath": "/",
  "schemes": [
    "https"
  ],
  "paths": {
    "/": {
      "get": {
        "description": "Method description.",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "schema": {
              "$ref": "#/definitions/Empty"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "Empty": {
      "type": "object",
      "title": "Empty Schema"
    }
  },
  "x-amazon-apigateway-documentation": {
    "version": "1.0.3",
    "documentationParts": [
      {
        "location": {
          "type": "API"
        },
        "properties": {
          "description": "API description",
          "info": {
            "description": "API info description 4",
            "version": "API info version 3"
          }
        }
      },
      {
        "location": {
          "type": "METHOD",
          "method": "GET"
        },
        "properties": {
          "description": "Method description."
        }
      },
      {
        "location": {
          "type": "MODEL",
          "name": "Empty"
        },
        "properties": {
          "title": "Empty Schema"
        }
      },
      {
        "location": {
          "type": "RESPONSE",
          "method": "GET",
          "statusCode": "200"
        },
        "properties": {
          "description": "200 response"
        }
      }
    ]
  }
}

성공하면 이 요청은 페이로드에 가져온 DocumentationPartId를 포함하는 200 OK 응답을 반환합니다.

{
  "ids": [
    "kg3mth",
    "796rtf",
    "zhek4p",
    "5ukm9s"
  ]
}

또한 restapi:import 또는 restapi:put을 호출하고 x-amazon-apigateway-documentation 객체의 설명서 부분을 API 정의의 입력 OpenAPI 파일의 부분으로 제공할 수도 있습니다. API 가져오기에서 설명서 부분을 제외하려면 요청 쿼리 파라미터에서 ignore=documentation을 설정하십시오.

API Gateway 콘솔을 사용하여 문서 부분 가져오기

다음 지침에서는 설명서 부분을 가져오는 방법을 설명합니다.

콘솔을 사용하여 외부 파일로부터 API의 설명서 부분 가져오는 방법

1. 기본 탐색 창에서 설명서를 선택합니다.

2. 가져오기를 선택합니다.

3. 기존 설명서가 있는 경우 새 문서에 대한 덮어쓰기 또는 병합 선택합니다.

4. 파일 선택을 선택하여 드라이브로부터 파일을 로드하거나 파일 내용을 파일 보기에 입력합니다. 예를 들어, API Gateway REST API를 사용하여 설명서 부분 가져오기에 포함된 예제 요청의 페이로드를 참조합니다.

5. 가져올 때 경고를 처리하는 방법을 선택합니다. 경고 실패 또는 경고 무시를 선택합니다. 자세한 내용은 가져오는 중 발생하는 오류 및 경고 섹션을 참조하세요.

6. [Import]를 선택합니다.