# Proceso de documentación de una API mediante la API de REST de API Gateway En esta sección se describe cómo crear y mantener piezas de documentación de una API mediante la API de REST de API Gateway. Antes de crear y editar la documentación de una API, primero debe crear la API. En esta sección, usaremos la API [PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets) como ejemplo. Para crear una API mediante la consola de API Gateway, siga las instrucciones de [Tutorial: Crear una API de REST importando un ejemplo](api-gateway-create-api-from-example.md). **Topics** + [Documentar la entidad `API`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-api) + [Documentar una entidad `RESOURCE`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-resource) + [Documentar una entidad `METHOD`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-method) + [Documentar una entidad `QUERY_PARAMETER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-query-parameter) + [Documentar una entidad `PATH_PARAMETER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-path-parameter) + [Documentar una entidad `REQUEST_BODY`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-body) + [Documentar una entidad `REQUEST_HEADER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-header) + [Documentar una entidad `RESPONSE`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response) + [Documentar una entidad `RESPONSE_HEADER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response-header) + [Documentar una entidad `AUTHORIZER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-authorizer) + [Documentar una entidad `MODEL`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-model) + [Actualización de las piezas de documentación](#api-gateway-documenting-api-quick-start-with-restapi-update-content) + [Mostrar piezas de documentación](#api-gateway-documenting-api-quick-start-with-restapi-list-parts) ## Documentar la entidad `API` Si desea agregar documentación sobre una [API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), agregue un recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) a la entidad 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}" } ``` Si es correcta, la operación devuelve una respuesta `201 Created` que contiene la instancia `DocumentationPart` recién creada en la carga. Por ejemplo: ``` { ... "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}" } ``` Si ya se ha agregado la pieza de documentación, se devuelve una respuesta `409 Conflict`, que contiene el mensaje de error `Documentation part already exists for the specified location: type 'API'."`. En este caso, debe llamar a la operación [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html). ``` 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}" } ] } ``` La respuesta correcta devuelve un código de estado `200 OK` con la carga que contiene la instancia `DocumentationPart` actualizada en la carga. ## Documentar una entidad `RESOURCE` Para agregar documentación para el recurso raíz de una API, agregue el recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) de destino para el recurso [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) correspondiente: ``` 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}" } ``` Si es correcta, la operación devuelve una respuesta `201 Created` que contiene la instancia `DocumentationPart` recién creada en la carga. Por ejemplo: ``` { "_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}" } ``` Cuando no se especifica la ruta del recurso, se considera que el recurso es el recurso raíz. Puede añadir `"path": "/"` a `properties` para que la especificación sea explícita. Para crear documentación para un recurso secundario de una API, agregue el recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) de destino para el recurso [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) correspondiente: ``` 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}" } ``` Si es correcta, la operación devuelve una respuesta `201 Created` que contiene la instancia `DocumentationPart` recién creada en la carga. Por ejemplo: ``` { "_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 agregar documentación para un recurso secundario especificado por un parámetro de ruta, agregue un recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) de destino para el recurso [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) correspondiente: ``` 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}" } ``` Si es correcta, la operación devuelve una respuesta `201 Created` que contiene la instancia `DocumentationPart` recién creada en la carga. Por ejemplo: ``` { "_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** La instancia de [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) de una entidad `RESOURCE` no la pueden heredar sus recursos secundarios. ## Documentar una entidad `METHOD` Para agregar documentación para un método de una API, agregue un recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) de destino para el recurso [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) correspondiente: ``` 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}" } ``` Si es correcta, la operación devuelve una respuesta `201 Created` que contiene la instancia `DocumentationPart` recién creada en la carga. Por ejemplo: ``` { "_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}" } ``` Si es correcta, la operación devuelve una respuesta `201 Created` que contiene la instancia `DocumentationPart` recién creada en la carga. Por ejemplo: ``` { "_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}" } ``` Si no se especifica el campo `location.method` en la solicitud anterior, se supone que se trata del método `ANY`, representado por un carácter comodín: `*`. Para actualizar el contenido de documentación de una entidad `METHOD`, llame a la operación [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html), proporcionando un nuevo mapa `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}" } ] } ``` La respuesta correcta devuelve un código de estado `200 OK` con la carga que contiene la instancia `DocumentationPart` actualizada en la carga. Por ejemplo: ``` { "_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 una entidad `QUERY_PARAMETER` Para agregar documentación para un parámetro de consulta de solicitud, agregue un recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) de destino para el tipo `QUERY_PARAMETER`, con los campos válidos `path` y `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}" } ``` Si es correcta, la operación devuelve una respuesta `201 Created` que contiene la instancia `DocumentationPart` recién creada en la carga. Por ejemplo: ``` { "_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}" } ``` El mapa `properties` de la pieza de documentación de una entidad `QUERY_PARAMETER` lo pueden heredar alguna de sus entidades `QUERY_PARAMETER` secundarias. Por ejemplo, si añade un recurso `treats` detrás de `/pets/{petId}`, habilita el método `GET` en `/pets/{petId}/treats` y expone el parámetro de consulta `page`, este parámetro de consulta secundario hereda el mapa `DocumentationPart` de `properties` desde el parámetro de consulta de igual nombre del método `GET /pets`, a menos que añada explícitamente un recurso `DocumentationPart` al parámetro de consulta `page` del método `GET /pets/{petId}/treats`. ## Documentar una entidad `PATH_PARAMETER` Para agregar documentación para un parámetro de ruta, agregue un recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) a la entidad `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}" } ``` Si es correcta, la operación devuelve una respuesta `201 Created` que contiene la instancia `DocumentationPart` recién creada en la carga. Por ejemplo: ``` { "_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 una entidad `REQUEST_BODY` Para agregar documentación para un cuerpo de solicitud, agregue un recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) al cuerpo de solicitud. ``` 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}" } ``` Si es correcta, la operación devuelve una respuesta `201 Created` que contiene la instancia `DocumentationPart` recién creada en la carga. Por ejemplo: ``` { "_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 una entidad `REQUEST_HEADER` Para agregar documentación para un encabezado de solicitud, agregue un recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) al encabezado de solicitud. ``` 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}" } ``` Si es correcta, la operación devuelve una respuesta `201 Created` que contiene la instancia `DocumentationPart` recién creada en la carga. Por ejemplo: ``` { "_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 una entidad `RESPONSE` Para agregar documentación para una respuesta de un código de estado, agregue un recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) de destino al recurso [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) correspondiente. ``` 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}" } ``` Si es correcta, la operación devuelve una respuesta `201 Created` que contiene la instancia `DocumentationPart` recién creada en la carga. Por ejemplo: ``` { "_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 una entidad `RESPONSE_HEADER` Para agregar documentación para un encabezado de respuesta, agregue un recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) al encabezado de respuesta. ``` 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}" ``` Si es correcta, la operación devuelve una respuesta `201 Created` que contiene la instancia `DocumentationPart` recién creada en la carga. Por ejemplo: ``` { "_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}" } ``` La documentación de este encabezado de respuesta `Content-Type` es la documentación predeterminada para los encabezados `Content-Type` de todas las respuestas de la API. ## Documentar una entidad `AUTHORIZER` Para agregar documentación para un autorizador de API, agregue un recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) de destino al 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}" } ``` Si es correcta, la operación devuelve una respuesta `201 Created` que contiene la instancia `DocumentationPart` recién creada en la carga. Por ejemplo: ``` { "_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** La instancia de [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) de una entidad `AUTHORIZER` no la pueden heredar sus recursos secundarios. ## Documentar una entidad `MODEL` Documentar una entidad `MODEL` implica crear y administrar instancias de `DocumentPart` para el modelo y para todas las `properties` del modelo. Por ejemplo, el modelo `Error` integrado con cada API de manera predeterminada tiene la siguiente definición de esquema ``` { "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "Error Schema", "type" : "object", "properties" : { "message" : { "type" : "string" } } } ``` y requiere dos instancias de `DocumentationPart`, una para `Model` y otra para su propiedad `message`: ``` { "location": { "type": "MODEL", "name": "Error" }, "properties": { "title": "Error Schema", "description": "A description of the Error model" } } ``` Protección de los datos ``` { "location": { "type": "MODEL", "name": "Error.message" }, "properties": { "description": "An error message." } } ``` Cuando se exporta la API, las propiedades de `DocumentationPart` invalidarán los valores del esquema original. Para agregar documentación para un modelo de API, agregue un recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) de destino al 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}" } ``` Si es correcta, la operación devuelve una respuesta `201 Created` que contiene la instancia `DocumentationPart` recién creada en la carga. Por ejemplo: ``` { "_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 el mismo paso si desea crear una instancia de DocumentationPart para cualquiera de las propiedades del modelo. **nota** La instancia de [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) de una entidad `MODEL` no la pueden heredar sus recursos secundarios. ## Actualización de las piezas de documentación Para actualizar las piezas de documentación de cualquier tipo de entidad de API, envíe una solicitud PATCH en una instancia de [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) de un identificador de pieza especificado para sustituir el mapa `properties` existente por uno nuevo. ``` 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" } ] } ``` La respuesta correcta devuelve un código de estado `200 OK` con la carga que contiene la instancia `DocumentationPart` actualizada en la carga. Puede actualizar varias piezas de documentación en una sola solicitud `PATCH`. ## Mostrar piezas de documentación Para mostrar las piezas de documentación de cualquier tipo de entidad de API, envíe una solicitud GET en una colección [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html). ``` 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 ``` La respuesta correcta devuelve un código de estado `200 OK` con la carga que contiene las instancias `DocumentationPart` disponibles en la carga.