이 단원에서는 API Gateway REST API를 사용하여 API의 설명서 부분을 생성하고 유지 관리하는 방법에 대해 설명합니다.
API 설명서를 생성 및 편집하기 전에 먼저 API를 만드십시오. 이 단원에서는 PetStore
주제
API 엔터티 문서화
API에 대한 설명서를 추가하려면 API 엔터티에 대한 DocumentationPart 리소스를 추가합니다.
POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret{ "location" : { "type" : "API" }, "properties": "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}" }
성공하면 해당 작업은 페이로드에서 새로 생성된 201 Created 인스턴스를 포함하는 DocumentationPart 응답을 반환합니다. 예:
{ ... "id": "s2e5xf", "location": { "path": null, "method": null, "name": null, "statusCode": null, "type": "API" }, "properties": "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}" }
설명서 부분이 이미 추가된 경우 409 Conflict의 오류 메시지를 포함하여 Documentation part already
exists for the specified location: type 'API'." 응답이 반환됩니다. 이 경우 documentationpart:update 작업을 호출해야 합니다.
PATCH /restapis/4wk1k4onj3/documentation/parts/part_idHTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: 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" : "/properties", "value" : "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}" } ] }
응답이 성공하면 업데이트된 200 OK 인스턴스를 포함한 페이로드와 함께 DocumentationPart 상태 코드를 반환합니다.
RESOURCE 엔터티 문서화
API의 루트 리소스에 대한 설명서를 추가하려면 해당 Resource 리소스를 대상으로 하는 DocumentationPart 리소스를 추가합니다.
POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret{ "location" : { "type" : "RESOURCE", }, "properties" : "{\n\t\"description\" : \"The PetStore root resource.\"\n}" }
성공하면 해당 작업은 페이로드에서 새로 생성된 201 Created 인스턴스를 포함하는 DocumentationPart 응답을 반환합니다. 예:
{ "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo" } }, "id": "p76vqo", "location": { "path": "/", "method": null, "name": null, "statusCode": null, "type": "RESOURCE" }, "properties": "{\n\t\"description\" : \"The PetStore root resource.\"\n}" }
리소스 경로가 지정되지 않은 경우 리소스가 루트 리소스로 간주됩니다. "path": "/"를 properties에 추가하여 명시적으로 지정할 수 있습니다.
API의 하위 리소스에 대한 설명서를 추가하려면 해당 Resource 리소스를 대상으로 하는 DocumentationPart 리소스를 추가합니다.
POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret{ "location" : { "type" : "RESOURCE", "path" : "/pets" }, "properties": "{\n\t\"description\" : \"A child resource under the root of PetStore.\"\n}" }
성공하면 해당 작업은 페이로드에서 새로 생성된 201 Created 인스턴스를 포함하는 DocumentationPart 응답을 반환합니다. 예:
{ "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/qcht86" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/qcht86" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/qcht86" } }, "id": "qcht86", "location": { "path": "/pets", "method": null, "name": null, "statusCode": null, "type": "RESOURCE" }, "properties": "{\n\t\"description\" : \"A child resource under the root of PetStore.\"\n}" }
경로 파라미터로 지정된 하위 리소스에 대한 설명서를 추가하려면 Resource 리소스를 대상으로 하는 DocumentationPart 리소스를 추가합니다.
POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret{ "location" : { "type" : "RESOURCE", "path" : "/pets/{petId}" }, "properties": "{\n\t\"description\" : \"A child resource specified by the petId path parameter.\"\n}" }
성공하면 해당 작업은 페이로드에서 새로 생성된 201 Created 인스턴스를 포함하는 DocumentationPart 응답을 반환합니다. 예:
{ "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb" } }, "id": "k6fpwb", "location": { "path": "/pets/{petId}", "method": null, "name": null, "statusCode": null, "type": "RESOURCE" }, "properties": "{\n\t\"description\" : \"A child resource specified by the petId path parameter.\"\n}" }
참고
RESOURCE 엔터티의 DocumentationPart 인스턴스는 하위 리소스가 상속할 수 없습니다.
METHOD 엔터티 문서화
API의 메서드에 대한 설명서를 추가하려면 해당 Method 리소스를 대상으로 하는 DocumentationPart 리소스를 추가합니다.
POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret{ "location" : { "type" : "METHOD", "path" : "/pets", "method" : "GET" }, "properties": "{\n\t\"summary\" : \"List all pets.\"\n}" }
성공하면 해당 작업은 페이로드에서 새로 생성된 201 Created 인스턴스를 포함하는 DocumentationPart 응답을 반환합니다. 예:
{ "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" } }, "id": "o64jbj", "location": { "path": "/pets", "method": "GET", "name": null, "statusCode": null, "type": "METHOD" }, "properties": "{\n\t\"summary\" : \"List all pets.\"\n}" }
성공하면 해당 작업은 페이로드에서 새로 생성된 201 Created 인스턴스를 포함하는 DocumentationPart 응답을 반환합니다. 예:
{ "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" } }, "id": "o64jbj", "location": { "path": "/pets", "method": "GET", "name": null, "statusCode": null, "type": "METHOD" }, "properties": "{\n\t\"summary\" : \"List all pets.\"\n}" }
이전 요청에서 location.method 필드가 지정되지 않은 경우 와일드카드 ANY 문자로 표현되는 * 메서드로 간주됩니다.
METHOD 엔터티의 설명서 콘텐츠를 업데이트하려면 documentationpart:update 작업을 호출하여 새 properties 맵을 제공합니다.
PATCH /restapis/4wk1k4onj3/documentation/parts/part_idHTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: 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" : "/properties", "value" : "{\n\t\"tags\" : [ \"pets\" ], \n\t\"summary\" : \"List all pets.\"\n}" } ] }
응답이 성공하면 업데이트된 200 OK 인스턴스를 포함한 페이로드와 함께 DocumentationPart 상태 코드를 반환합니다. 예:
{ "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" } }, "id": "o64jbj", "location": { "path": "/pets", "method": "GET", "name": null, "statusCode": null, "type": "METHOD" }, "properties": "{\n\t\"tags\" : [ \"pets\" ], \n\t\"summary\" : \"List all pets.\"\n}" }
QUERY_PARAMETER 엔터티 문서화
요청 쿼리 파라미터에 대한 설명서를 추가하려면 QUERY_PARAMETER 및 path의 유효한 필드를 사용하여 name 유형을 대상으로 하는 DocumentationPart 리소스를 추가합니다.
POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret{ "location" : { "type" : "QUERY_PARAMETER", "path" : "/pets", "method" : "GET", "name" : "page" }, "properties": "{\n\t\"description\" : \"Page number of results to return.\"\n}" }
성공하면 해당 작업은 페이로드에서 새로 생성된 201 Created 인스턴스를 포함하는 DocumentationPart 응답을 반환합니다. 예:
{ "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w" } }, "id": "h9ht5w", "location": { "path": "/pets", "method": "GET", "name": "page", "statusCode": null, "type": "QUERY_PARAMETER" }, "properties": "{\n\t\"description\" : \"Page number of results to return.\"\n}" }
properties 엔터티의 설명서 부분의 QUERY_PARAMETER 맵은 QUERY_PARAMETER 하위 엔터티 중 하나만 상속할 수 있습니다. 예를 들어, treats 다음에 /pets/{petId} 리소스를 추가하고, GET에서 /pets/{petId}/treats 메서드를 활성화하고, page 쿼리 파라미터를 표시한 경우, 사용자가 DocumentationPart 리소스를 properties 메서드의 GET /pets 쿼리 파라미터에 명시적으로 추가하지 않으면 이 하위 쿼리 파라미터는 DocumentationPart 메서드의 이름이 같은 쿼리 파라미터에서 page의 GET /pets/{petId}/treats 맵을 상속합니다.
PATH_PARAMETER 엔터티 문서화
경로 파라미터에 대한 설명서를 추가하려면 PATH_PARAMETER 엔터티에 대한 DocumentationPart 리소스를 추가합니다.
POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret{ "location" : { "type" : "PATH_PARAMETER", "path" : "/pets/{petId}", "method" : "*", "name" : "petId" }, "properties": "{\n\t\"description\" : \"The id of the pet to retrieve.\"\n}" }
성공하면 해당 작업은 페이로드에서 새로 생성된 201 Created 인스턴스를 포함하는 DocumentationPart 응답을 반환합니다. 예:
{ "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog" } }, "id": "ckpgog", "location": { "path": "/pets/{petId}", "method": "*", "name": "petId", "statusCode": null, "type": "PATH_PARAMETER" }, "properties": "{\n \"description\" : \"The id of the pet to retrieve\"\n}" }
REQUEST_BODY 엔터티 문서화
요청 본문에 대한 설명서를 추가하려면 요청 본문에 대한 DocumentationPart 리소스를 추가합니다.
POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret{ "location" : { "type" : "REQUEST_BODY", "path" : "/pets", "method" : "POST" }, "properties": "{\n\t\"description\" : \"A Pet object to be added to PetStore.\"\n}" }
성공하면 해당 작업은 페이로드에서 새로 생성된 201 Created 인스턴스를 포함하는 DocumentationPart 응답을 반환합니다. 예:
{ "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1" } }, "id": "kgmfr1", "location": { "path": "/pets", "method": "POST", "name": null, "statusCode": null, "type": "REQUEST_BODY" }, "properties": "{\n\t\"description\" : \"A Pet object to be added to PetStore.\"\n}" }
REQUEST_HEADER 엔터티 문서화
요청 헤더에 대한 설명서를 추가하려면 요청 헤더에 대한 DocumentationPart 리소스를 추가합니다.
POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret{ "location" : { "type" : "REQUEST_HEADER", "path" : "/pets", "method" : "GET", "name" : "x-my-token" }, "properties": "{\n\t\"description\" : \"A custom token used to authorization the method invocation.\"\n}" }
성공하면 해당 작업은 페이로드에서 새로 생성된 201 Created 인스턴스를 포함하는 DocumentationPart 응답을 반환합니다. 예:
{ "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf" } }, "id": "h0m3uf", "location": { "path": "/pets", "method": "GET", "name": "x-my-token", "statusCode": null, "type": "REQUEST_HEADER" }, "properties": "{\n\t\"description\" : \"A custom token used to authorization the method invocation.\"\n}" }
RESPONSE 엔터티 문서화
상태 코드의 응답에 대한 설명서를 추가하려면 해당 MethodResponse 리소스를 대상으로 하는 DocumentationPart 리소스를 추가합니다.
POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret{ "location": { "path": "/", "method": "*", "name": null, "statusCode": "200", "type": "RESPONSE" }, "properties": "{\n \"description\" : \"Successful operation.\"\n}" }
성공하면 해당 작업은 페이로드에서 새로 생성된 201 Created 인스턴스를 포함하는 DocumentationPart 응답을 반환합니다. 예:
{ "_links": { "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/lattew" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/lattew" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/lattew" } }, "id": "lattew", "location": { "path": "/", "method": "*", "name": null, "statusCode": "200", "type": "RESPONSE" }, "properties": "{\n \"description\" : \"Successful operation.\"\n}" }
RESPONSE_HEADER 엔터티 문서화
응답 헤더에 대한 설명서를 추가하려면 응답 헤더에 대한 DocumentationPart 리소스를 추가합니다.
POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret"location": { "path": "/", "method": "GET", "name": "Content-Type", "statusCode": "200", "type": "RESPONSE_HEADER" }, "properties": "{\n \"description\" : \"Media type of request\"\n}"
성공하면 해당 작업은 페이로드에서 새로 생성된 201 Created 인스턴스를 포함하는 DocumentationPart 응답을 반환합니다. 예:
{ "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7" } }, "id": "fev7j7", "location": { "path": "/", "method": "GET", "name": "Content-Type", "statusCode": "200", "type": "RESPONSE_HEADER" }, "properties": "{\n \"description\" : \"Media type of request\"\n}" }
이 Content-Type 응답 헤더의 설명서는 모든 API 응답의 Content-Type 헤더에 대한 기본 설명서입니다.
AUTHORIZER 엔터티 문서화
API 권한 부여자에 대한 설명서를 추가하려면 지정된 권한 부여자를 대상으로 하는 DocumentationPart 리소스를 추가합니다.
POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret{ "location" : { "type" : "AUTHORIZER", "name" : "myAuthorizer" }, "properties": "{\n\t\"description\" : \"Authorizes invocations of configured methods.\"\n}" }
성공하면 해당 작업은 페이로드에서 새로 생성된 201 Created 인스턴스를 포함하는 DocumentationPart 응답을 반환합니다. 예:
{ "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3" } }, "id": "pw3qw3", "location": { "path": null, "method": null, "name": "myAuthorizer", "statusCode": null, "type": "AUTHORIZER" }, "properties": "{\n\t\"description\" : \"Authorizes invocations of configured methods.\"\n}" }
참고
AUTHORIZER 엔터티의 DocumentationPart 인스턴스는 하위 리소스가 상속할 수 없습니다.
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'의 속성이 원본 스키마의 값을 재정의합니다.
API 모델에 대한 설명서를 추가하려면 지정된 모델을 대상으로 하는 DocumentationPart 리소스를 추가합니다.
POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret{ "location" : { "type" : "MODEL", "name" : "Pet" }, "properties": "{\n\t\"description\" : \"Data structure of a Pet object.\"\n}" }
성공하면 해당 작업은 페이로드에서 새로 생성된 201 Created 인스턴스를 포함하는 DocumentationPart 응답을 반환합니다. 예:
{ "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq" } }, "id": "lkn4uq", "location": { "path": null, "method": null, "name": "Pet", "statusCode": null, "type": "MODEL" }, "properties": "{\n\t\"description\" : \"Data structure of a Pet object.\"\n}" }
동일한 단계를 반복하여 모델의 속성에 대한 DocumentationPart 인스턴스를 생성합니다.
참고
MODEL 엔터티의 DocumentationPart 인스턴스는 하위 리소스가 상속할 수 없습니다.
설명서 부분 업데이트
모든 API 엔터티 유형의 설명서 부분을 업데이트하려면 지정된 부분 식별자의 DocumentationPart 인스턴스에서 PATCH 요청을 제출하여 기존 properties 맵을 새로운 맵으로 교체합니다.
PATCH /restapis/4wk1k4onj3/documentation/parts/part_idHTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: 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" : "RESOURCE_PATH", "value" : "NEW_properties_VALUE_AS_JSON_STRING" } ] }
응답이 성공하면 업데이트된 200 OK 인스턴스를 포함한 페이로드와 함께 DocumentationPart 상태 코드를 반환합니다.
단일 PATCH 요청으로 여러 설명서 부분을 업데이트할 수 있습니다.
설명서 부분 나열
모든 API 엔터티 유형의 설명서 부분을 나열하려면 DocumentationParts 컬렉션에서 GET 요청을 제출합니다.
GET /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
응답이 성공하면 사용 가능한 200 OK 인스턴스를 포함한 페이로드와 함께 DocumentationPart 상태 코드를 반환합니다.
