Documentar uma API usando a API REST do API Gateway
Nesta seção, descrevemos como criar e manter partes da documentação de uma API usando a API REST do API Gateway.
Crie uma API antes de criar e editar sua documentação. Nesta seção, usamos a API PetStore
Tópicos
- Documentar a entidade API
- Documentar uma entidade RESOURCE
- Documentar uma entidade METHOD
- Documentar uma entidade QUERY_PARAMETER
- Documentar uma entidade PATH_PARAMETER
- Documentar uma entidade REQUEST_BODY
- Documentar uma entidade REQUEST_HEADER
- Documentar uma entidade RESPONSE
- Documentar uma entidade RESPONSE_HEADER
- Documentar uma entidade AUTHORIZER
- Documentar uma entidade MODEL
- Atualizar partes da documentação
- Listar partes da documentação
Documentar a entidade API
Para adicionar documentação para uma API, adicione um recurso DocumentationPart à entidade de API:
POST /restapis/
restapi_id
/documentation/parts 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
{ "location" : { "type" : "API" }, "properties": "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}" }
Se bem-sucedida, a operação retornará uma resposta 201 Created
, contendo a instância DocumentationPart
recém-criada na carga útil. Por exemplo:
{ ... "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}" }
Se a parte de documentação já tiver sido adicionada, será retornada uma resposta 409 Conflict
contendo a mensagem de erro Documentation part already
exists for the specified location: type 'API'."
. Nesse caso, você deve chamar a operação documentationpart:update.
PATCH /restapis/4wk1k4onj3/documentation/parts/
part_id
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" : "/properties", "value" : "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}" } ] }
A resposta bem-sucedida retorna um código de status 200 OK
com a carga útil que contém a instância DocumentationPart
atualizada.
Documentar uma entidade RESOURCE
Para adicionar a documentação do recurso raiz de uma API, adicione um recurso DocumentationPart direcionado ao recurso Resource correspondente:
POST /restapis/
restapi_id
/documentation/parts 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
{ "location" : { "type" : "RESOURCE", }, "properties" : "{\n\t\"description\" : \"The PetStore root resource.\"\n}" }
Se bem-sucedida, a operação retornará uma resposta 201 Created
, contendo a instância DocumentationPart
recém-criada na carga útil. Por exemplo:
{ "_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}" }
Quando o caminho do recurso não é especificado, supõe-se que esse recurso seja raiz. Você pode adicionar "path": "/"
a properties
para tornar a especificação explícita.
Para criar a documentação de um recurso filho de uma API, adicione um recurso DocumentationPart direcionado ao recurso Resource correspondente:
POST /restapis/
restapi_id
/documentation/parts 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
{ "location" : { "type" : "RESOURCE", "path" : "/pets" }, "properties": "{\n\t\"description\" : \"A child resource under the root of PetStore.\"\n}" }
Se bem-sucedida, a operação retornará uma resposta 201 Created
, contendo a instância DocumentationPart
recém-criada na carga útil. Por exemplo:
{ "_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}" }
Para adicionar a documentação de um recurso filho especificado por um parâmetro de caminho, adicione um recurso DocumentationPart direcionado ao recurso Resource:
POST /restapis/
restapi_id
/documentation/parts 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
{ "location" : { "type" : "RESOURCE", "path" : "/pets/{petId}" }, "properties": "{\n\t\"description\" : \"A child resource specified by the petId path parameter.\"\n}" }
Se bem-sucedida, a operação retornará uma resposta 201 Created
, contendo a instância DocumentationPart
recém-criada na carga útil. Por exemplo:
{ "_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}" }
nota
A instância de DocumentationPart de uma entidade RESOURCE
não pode ser herdada por nenhum de seus recursos filho.
Documentar uma entidade METHOD
Para adicionar a documentação para um método de uma API, adicione um recurso DocumentationPart direcionado ao recurso Method correspondente:
POST /restapis/
restapi_id
/documentation/parts 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
{ "location" : { "type" : "METHOD", "path" : "/pets", "method" : "GET" }, "properties": "{\n\t\"summary\" : \"List all pets.\"\n}" }
Se bem-sucedida, a operação retornará uma resposta 201 Created
, contendo a instância DocumentationPart
recém-criada na carga útil. Por exemplo:
{ "_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}" }
Se bem-sucedida, a operação retornará uma resposta 201 Created
, contendo a instância DocumentationPart
recém-criada na carga útil. Por exemplo:
{ "_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}" }
Se o campo location.method
não for especificado na solicitação anterior, supõe-se que ele seja o método ANY
que é representado por um caractere curinga *
.
Para atualizar o conteúdo de documentação de uma entidade METHOD
, chame a operação documentationpart:update, fornecendo um novo mapa de properties
:
PATCH /restapis/4wk1k4onj3/documentation/parts/
part_id
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" : "/properties", "value" : "{\n\t\"tags\" : [ \"pets\" ], \n\t\"summary\" : \"List all pets.\"\n}" } ] }
A resposta bem-sucedida retorna um código de status 200 OK
com a carga útil que contém a instância DocumentationPart
atualizada. Por exemplo:
{ "_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}" }
Documentar uma entidade QUERY_PARAMETER
Para adicionar a documentação de um parâmetro de consulta de solicitação, adicione um recurso DocumentationPart direcionado ao tipo QUERY_PARAMETER
, com os campos válidos de path
e name
.
POST /restapis/
restapi_id
/documentation/parts 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
{ "location" : { "type" : "QUERY_PARAMETER", "path" : "/pets", "method" : "GET", "name" : "page" }, "properties": "{\n\t\"description\" : \"Page number of results to return.\"\n}" }
Se bem-sucedida, a operação retornará uma resposta 201 Created
, contendo a instância DocumentationPart
recém-criada na carga útil. Por exemplo:
{ "_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}" }
O mapa de properties
da parte de documentação de uma entidade QUERY_PARAMETER
pode ser herdado por uma de suas entidades QUERY_PARAMETER
filho. Por exemplo, se você adicionar um recurso treats
depois de /pets/{petId}
, habilitar o método GET
em /pets/{petId}/treats
e expor o parâmetro de consulta page
, esse parâmetro de consulta filho herdará o mapa DocumentationPart
de properties
do parâmetro de consulta com nome semelhante do método GET /pets
, a menos que você adicione explicitamente um recurso DocumentationPart
ao parâmetro de consulta page
do método GET /pets/{petId}/treats
.
Documentar uma entidade PATH_PARAMETER
Para adicionar a documentação de um parâmetro de caminho, adicione um recurso DocumentationPart para a entidade PATH_PARAMETER
.
POST /restapis/
restapi_id
/documentation/parts 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
{ "location" : { "type" : "PATH_PARAMETER", "path" : "/pets/{petId}", "method" : "*", "name" : "petId" }, "properties": "{\n\t\"description\" : \"The id of the pet to retrieve.\"\n}" }
Se bem-sucedida, a operação retornará uma resposta 201 Created
, contendo a instância DocumentationPart
recém-criada na carga útil. Por exemplo:
{ "_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}" }
Documentar uma entidade REQUEST_BODY
Para adicionar a documentação de um corpo de solicitação, adicione um recurso DocumentationPart para o corpo da solicitação.
POST /restapis/
restapi_id
/documentation/parts 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
{ "location" : { "type" : "REQUEST_BODY", "path" : "/pets", "method" : "POST" }, "properties": "{\n\t\"description\" : \"A Pet object to be added to PetStore.\"\n}" }
Se bem-sucedida, a operação retornará uma resposta 201 Created
, contendo a instância DocumentationPart
recém-criada na carga útil. Por exemplo:
{ "_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}" }
Documentar uma entidade REQUEST_HEADER
Para adicionar a documentação de um cabeçalho de solicitação, adicione um recurso DocumentationPart para o cabeçalho da solicitação.
POST /restapis/
restapi_id
/documentation/parts 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
{ "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}" }
Se bem-sucedida, a operação retornará uma resposta 201 Created
, contendo a instância DocumentationPart
recém-criada na carga útil. Por exemplo:
{ "_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}" }
Documentar uma entidade RESPONSE
Para adicionar a documentação para uma resposta de um código de status, adicione um recurso DocumentationPart direcionado para o recurso MethodResponse correspondente.
POST /restapis/
restapi_id
/documentation/parts 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
{ "location": { "path": "/", "method": "*", "name": null, "statusCode": "200", "type": "RESPONSE" }, "properties": "{\n \"description\" : \"Successful operation.\"\n}" }
Se bem-sucedida, a operação retornará uma resposta 201 Created
, contendo a instância DocumentationPart
recém-criada na carga útil. Por exemplo:
{ "_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}" }
Documentar uma entidade RESPONSE_HEADER
Para adicionar a documentação de um cabeçalho de resposta, adicione um recurso DocumentationPart para o cabeçalho da solicitação.
POST /restapis/
restapi_id
/documentation/parts 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
"location": { "path": "/", "method": "GET", "name": "Content-Type", "statusCode": "200", "type": "RESPONSE_HEADER" }, "properties": "{\n \"description\" : \"Media type of request\"\n}"
Se bem-sucedida, a operação retornará uma resposta 201 Created
, contendo a instância DocumentationPart
recém-criada na carga útil. Por exemplo:
{ "_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}" }
A documentação desse cabeçalho de resposta Content-Type
é a documentação padrão para os cabeçalhos Content-Type
de todas as respostas da API.
Documentar uma entidade AUTHORIZER
Para adicionar a documentação de um autorizador de API, adicione um recurso DocumentationPart direcionado ao autorizador especificado.
POST /restapis/
restapi_id
/documentation/parts 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
{ "location" : { "type" : "AUTHORIZER", "name" : "myAuthorizer" }, "properties": "{\n\t\"description\" : \"Authorizes invocations of configured methods.\"\n}" }
Se bem-sucedida, a operação retornará uma resposta 201 Created
, contendo a instância DocumentationPart
recém-criada na carga útil. Por exemplo:
{ "_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}" }
nota
A instância de DocumentationPart de uma entidade AUTHORIZER
não pode ser herdada por nenhum de seus recursos filho.
Documentar uma entidade MODEL
A documentação de uma entidade MODEL
envolve a criação e o gerenciamento de instâncias de DocumentPart
para o modelo e cada uma das properties
do modelo. Por exemplo, o modelo Error
que acompanha cada API por padrão tem a seguinte definição de esquema,
{ "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "Error Schema", "type" : "object", "properties" : { "message" : { "type" : "string" } } }
e requer duas instâncias de DocumentationPart
, uma para o Model
e a outra para sua propriedade message
:
{ "location": { "type": "MODEL", "name": "Error" }, "properties": { "title": "Error Schema", "description": "A description of the Error model" } }
e
{ "location": { "type": "MODEL", "name": "Error.message" }, "properties": { "description": "An error message." } }
Quando a API for exportada, as propriedades de DocumentationPart
substituirão os valores no esquema original.
Para adicionar a documentação de um modelo de API, adicione um recurso DocumentationPart direcionado ao modelo especificado.
POST /restapis/
restapi_id
/documentation/parts 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
{ "location" : { "type" : "MODEL", "name" : "Pet" }, "properties": "{\n\t\"description\" : \"Data structure of a Pet object.\"\n}" }
Se bem-sucedida, a operação retornará uma resposta 201 Created
, contendo a instância DocumentationPart
recém-criada na carga útil. Por exemplo:
{ "_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}" }
Repita a mesma etapa para criar uma instância de DocumentationPart para qualquer uma das propriedades do modelo.
nota
A instância de DocumentationPart de uma entidade MODEL
não pode ser herdada por nenhum de seus recursos filho.
Atualizar partes da documentação
Para atualizar as partes de documentação de qualquer tipo de entidade de API, envie uma solicitação PATCH em uma instância de DocumentationPart de um identificador de parte especificado para substituir o mapa de properties
existente por um novo.
PATCH /restapis/4wk1k4onj3/documentation/parts/
part_id
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" : "RESOURCE_PATH
", "value" : "NEW_properties_VALUE_AS_JSON_STRING
" } ] }
A resposta bem-sucedida retorna um código de status 200 OK
com a carga útil que contém a instância DocumentationPart
atualizada.
Você pode atualizar várias partes de documentação em uma única solicitação PATCH
.
Listar partes da documentação
Para listar as partes de documentação de qualquer tipo de entidade de API, envie uma solicitação GET em uma coleção DocumentationParts.
GET /restapis/
restapi_id
/documentation/parts 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
A resposta bem-sucedida retorna um código de status 200 OK
com a carga útil que contém as instâncias DocumentationPart
disponíveis.