API 설명서 가져오기 - Amazon API Gateway

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

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. 콘솔의 기본 탐색 창에서 API에 대해 설명서를 선택합니다.

  2. 설명서 창에서 설명서 가져오기(Import Documentation)를 선택합니다.

  3. Select OpenAPI File(OpenAPI 파일 선택)을 선택하여 드라이브로부터 파일을 로드하거나 파일 내용을 파일 보기로 복사하여 붙여 넣습니다. 예를 들어, API Gateway REST API를 사용하여 설명서 부분 가져오기에 포함된 예제 요청의 페이로드를 참조합니다.

  4. 필요에 따라 경고 실패(Fail on warnings) 또는 경고 무시(Ignore warnings)를 선택하고 가져오기 모드(Import mode)에서 Merge 또는 Overwrite를 선택합니다.

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