# Publicación de documentación de la API mediante la API de REST de API Gateway
Para publicar la documentación de una API, cree, actualice u obtenga una snapshot de documentación y después asóciela a una etapa de API. Cuando crea una snapshot de documentación, también puede asociarla a una etapa de API al mismo tiempo.
**Topics**
+ [Crear una snapshot de documentación y asociarla a una etapa de API](#api-gateway-documenting-api-publishing-create-documentation-version-with-stage)
+ [Crear una snapshot de documentación](#api-gateway-documenting-api-publishing-create-documentation-version)
+ [Actualizar una snapshot de documentación](#api-gateway-documenting-api-publishing-update-documentation-version)
+ [Obtener una snapshot de documentación](#api-gateway-documenting-api-publishing-get-documentation-version)
+ [Asociar una snapshot de documentación con una etapa de API](#api-gateway-documenting-api-publishing-stage-association)
+ [Descargar una snapshot de documentación asociada a una etapa](#api-gateway-documenting-api-publishing-export-documentation-version)
## Crear una snapshot de documentación y asociarla a una etapa de API
Para crear una snapshot de piezas de documentación de una API y asociarla a una etapa de API al mismo tiempo, envíe la siguiente solicitud `POST`:
```
POST /restapis/restapi_id/documentation/versions 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
{
"documentationVersion" : "1.0.0",
"stageName": "prod",
"description" : "My API Documentation v1.0.0"
}
```
Si es correcta, la operación devuelve una respuesta `200 OK` que contiene la instancia `DocumentationVersion` recién creada como la carga.
También puede crear una instantánea de documentación sin asociarla primero a una etapa de API y después llamar a [restapi:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) para asociar la instantánea a una etapa de API específica. También puede actualizar o consultar una snapshot de documentación existente y después actualizar su asociación de etapa. Le mostramos los pasos en las próximas cuatro secciones.
## Crear una snapshot de documentación
Para crear una instantánea de piezas de documentación de una API, cree un nuevo recurso [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) y agréguelo a la colección [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) de la API:
```
POST /restapis/restapi_id/documentation/versions 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
{
"documentationVersion" : "1.0.0",
"description" : "My API Documentation v1.0.0"
}
```
Si es correcta, la operación devuelve una respuesta `200 OK` que contiene la instancia `DocumentationVersion` recién creada como la carga.
## Actualizar una snapshot de documentación
Solo puede actualizar una instantánea de documentación modificando la propiedad `description` del recurso [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) correspondiente. El siguiente ejemplo muestra cómo actualizar la descripción de la snapshot de documentación identificada por su identificador de versión, `version` (p. ej., `1.0.0`).
```
PATCH /restapis/restapi_id/documentation/versions/version 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": "/description",
"value": "My API for testing purposes."
}]
}
```
Si es correcta, la operación devuelve una respuesta `200 OK` que contiene la instancia `DocumentationVersion` actualizada como la carga.
## Obtener una snapshot de documentación
Para obtener una instantánea de documentación, envíe una solicitud `GET` al recurso [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) especificado. El siguiente ejemplo muestra cómo obtener una snapshot de documentación de un identificador de versión determinado, 1.0.0.
```
GET /restapis//documentation/versions/1.0.0 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
```
## Asociar una snapshot de documentación con una etapa de API
Para publicar la documentación de la API, asocie una snapshot de documentación a una etapa de API. Debe haber creado una etapa de API antes de asociar la versión de documentación a la etapa.
Para asociar una instantánea de documentación a una etapa de API, mediante la [API de REST de API Gateway](https://docs.aws.amazon.com/apigateway/latest/api/), llame a la operación [stage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) para establecer la versión de documentación que desee en la propiedad `stage.documentationVersion`:
```
PATCH /restapis/RESTAPI_ID/stages/STAGE_NAME
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": "/documentationVersion",
"value": "VERSION_IDENTIFIER"
}]
}
```
## Descargar una snapshot de documentación asociada a una etapa
Una vez asociada una versión de las partes de la documentación a una etapa, puede exportar las partes de la documentación junto con las definiciones de la entidad de la API a un archivo externo mediante la consola de API Gateway, la API REST de API Gateway, uno de sus SDK o la AWS CLI para API Gateway. El proceso es el mismo que para exportar la API. El formato del archivo exportado puede ser JSON o YAML.
Mediante la API de REST de API Gateway, también puede establecer explícitamente el parámetro de consulta `extension=documentation,integrations,authorizers` para incluir las piezas de documentación de la API, las integraciones de la API y los autorizadores en una exportación de la API. De forma predeterminada, se incluyen las piezas de documentación, pero se excluyen las integraciones y los autorizadores cuando se exporta una API. La salida predeterminada de la exportación de API es adecuada para la distribución de la documentación.
Para exportar la documentación de la API en un archivo JSON de OpenAPI externo mediante la API de REST de API Gateway, envíe la siguiente solicitud `GET`:
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=documentation HTTP/1.1
Accept: application/json
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
```
Aquí, el objeto `x-amazon-apigateway-documentation` contiene las piezas de documentación y las definiciones de la entidad de API contienen las propiedades de documentación admitidas por OpenAPI. La salida no incluye los detalles de la integración ni de los autorizadores de Lambda (que anteriormente se denominaban autorizadores personalizados). Para incluir ambos detalles, establezca `extensions=integrations,authorizers,documentation`. Para incluir los detalles de las integraciones pero no de los autorizadores, establezca `extensions=integrations,documentation`.
Debe definir el encabezado `Accept:application/json` en la solicitud para mostrar el resultado en un archivo JSON. Para producir la salida en formato YAML, cambie el encabezado de la solicitud a `Accept:application/yaml`.
A modo de ejemplo, vamos a examinar una API que expone un método `GET` sencillo en el recurso raíz (`/`). Esta API tiene cuatro entidades de API definidas en un archivo de definición de OpenAPI, una para cada uno de los tipos `API`, `MODEL`, `METHOD` y `RESPONSE`. Se ha añadido una pieza de documentación a cada una de las entidades `API`, `METHOD` y `RESPONSE`. Al llamar al comando de exportación de la documentación anterior, obtenemos el siguiente resultado, con las piezas de documentación mostradas dentro del objeto `x-amazon-apigateway-documentation` como una extensión a un archivo de OpenAPI estándar.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"description": "API info description",
"version": "2016-11-22T22:39:14Z",
"title": "doc",
"x-bar": "API info x-bar"
},
"paths": {
"/": {
"get": {
"description": "Method description.",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-example": "x- Method example"
},
"x-bar": "resource x-bar"
}
},
"x-amazon-apigateway-documentation": {
"version": "1.0.0",
"createdDate": "2016-11-22T22:41:40Z",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"foo": "API foo",
"x-bar": "API x-bar",
"info": {
"description": "API info description",
"version": "API info version",
"foo": "API info foo",
"x-bar": "API info x-bar"
}
}
},
{
"location": {
"type": "METHOD",
"method": "GET"
},
"properties": {
"description": "Method description.",
"x-example": "x- Method example",
"foo": "Method foo",
"info": {
"version": "method info version",
"description": "method info description",
"foo": "method info foo"
}
}
},
{
"location": {
"type": "RESOURCE"
},
"properties": {
"description": "resource description",
"foo": "resource foo",
"x-bar": "resource x-bar",
"info": {
"description": "resource info description",
"version": "resource info version",
"foo": "resource info foo",
"x-bar": "resource info x-bar"
}
}
}
]
},
"x-bar": "API x-bar",
"servers": [
{
"url": "https://rznaap68yi.execute-api.ap-southeast-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/test"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"description" : "API info description",
"version" : "2016-11-22T22:39:14Z",
"title" : "doc",
"x-bar" : "API info x-bar"
},
"host" : "rznaap68yi.execute-api.ap-southeast-1.amazonaws.com",
"basePath" : "/test",
"schemes" : [ "https" ],
"paths" : {
"/" : {
"get" : {
"description" : "Method description.",
"produces" : [ "application/json" ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/Empty"
}
}
},
"x-example" : "x- Method example"
},
"x-bar" : "resource x-bar"
}
},
"definitions" : {
"Empty" : {
"type" : "object",
"title" : "Empty Schema"
}
},
"x-amazon-apigateway-documentation" : {
"version" : "1.0.0",
"createdDate" : "2016-11-22T22:41:40Z",
"documentationParts" : [ {
"location" : {
"type" : "API"
},
"properties" : {
"description" : "API description",
"foo" : "API foo",
"x-bar" : "API x-bar",
"info" : {
"description" : "API info description",
"version" : "API info version",
"foo" : "API info foo",
"x-bar" : "API info x-bar"
}
}
}, {
"location" : {
"type" : "METHOD",
"method" : "GET"
},
"properties" : {
"description" : "Method description.",
"x-example" : "x- Method example",
"foo" : "Method foo",
"info" : {
"version" : "method info version",
"description" : "method info description",
"foo" : "method info foo"
}
}
}, {
"location" : {
"type" : "RESOURCE"
},
"properties" : {
"description" : "resource description",
"foo" : "resource foo",
"x-bar" : "resource x-bar",
"info" : {
"description" : "resource info description",
"version" : "resource info version",
"foo" : "resource info foo",
"x-bar" : "resource info x-bar"
}
}
} ]
},
"x-bar" : "API x-bar"
}
```
------
Para un atributo compatible con OpenAPI definido en el mapa `properties` de una pieza de documentación, API Gateway inserta el atributo en la definición de la entidad de API asociada. Un atributo de `x-something` es una extensión de OpenAPI estándar. Esta extensión se propaga a la definición de la entidad de API. Véase, por ejemplo, el atributo `x-example` del método `GET`. Un atributo como `foo` no forma parte de la especificación de OpenAPI y no se incluye en sus definiciones de entidad de API asociadas.
Si una herramienta de representación de la documentación (por ejemplo, la [interfaz de usuario de OpenAPI](https://swagger.io/tools/swagger-ui/)) analiza las definiciones de la entidad de API para extraer los atributos de documentación, ninguno de los atributos `properties` que no sean compatibles con OpenAPI de una instancia de `DocumentationPart` estará disponible para la herramienta. Sin embargo, si una herramienta de representación de documentación analiza el objeto `x-amazon-apigateway-documentation` para obtener contenido, o si la herramienta llama a [restapi:documentation-parts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) y [documenationpart:by-id](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationPart.html) para recuperar piezas de documentación de API Gateway, la herramienta podrá mostrar todos los atributos de la documentación.
Para exportar la documentación con definiciones de entidad de API que contengan detalles de la integración en un archivo JSON de OpenAPI, envíe la siguiente solicitud `GET`:
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,documentation HTTP/1.1
Accept: application/json
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
```
Para exportar la documentación con definiciones de entidad de API que contengan detalles de las integraciones y autorizadores a un archivo YAML de OpenAPI, envíe la siguiente solicitud `GET`:
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,authorizers,documentation HTTP/1.1
Accept: application/yaml
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
```
Para utilizar la consola de API Gateway para exportar y descargar la documentación publicada de una API, siga las instrucciones de [Exportar API REST con la consola de API Gateway](api-gateway-export-api.md#api-gateway-export-api-from-console).