# Documentación para las API de REST en API Gateway Para ayudar a los clientes a comprender y utilizar la API, debe documentar la API. Para ayudar a documentar su API, API Gateway le permite agregar y actualizar el contenido de la ayuda de las distintas entidades de API como parte integral de su proceso de desarrollo de la API. API Gateway almacena el contenido de origen y le permite archivar diferentes versiones de la documentación. Puede asociar una versión de la documentación a una etapa de la API, exportar una instantánea de documentación específica de la etapa a un archivo de OpenAPI externo y distribuir el archivo como una publicación de la documentación. Para documentar la API, puede llamar a la [API de REST de API Gateway](https://docs.aws.amazon.com/apigateway/latest/api/), utilizar uno de los [AWS SDK](https://aws.amazon.com/developer/tools/), la [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/apigateway/) para API Gateway o usar la consola de API Gateway. Además, puede importar o exportar las piezas de la documentación definidas en un archivo de OpenAPI externo. Para compartir la documentación de la API con los desarrolladores, puede usar un portal para desarrolladores. Para ver un ejemplo, consulte [Integrating ReadMe with API Gateway to Keep Your Developer Hub Up to Date](https://aws.amazon.com/blogs/apn/integrating-readme-with-amazon-api-gateway-to-keep-your-developer-hub-up-to-date/) o [How to Streamline API Development on Amazon API Gateway Using SmartBear’s SwaggerHub](https://aws.amazon.com/blogs/apn/how-to-streamline-api-development-on-amazon-api-gateway-using-smartbear-swaggerhub/) en el blog de Red de socios (APN) de AWS. **Topics** + [ # Representación de la documentación de la API en API Gateway ](api-gateway-documenting-api-content-representation.md) + [ # Proceso de documentación de una API mediante la consola API Gateway ](api-gateway-documenting-api-quick-start-with-console.md) + [ # Publicación de documentación de la API mediante la consola de API Gateway ](apigateway-documenting-api-with-console.md) + [ # Proceso de documentación de una API mediante la API de REST de API Gateway ](api-gateway-documenting-api-quick-start-with-restapi.md) + [ # Publicación de documentación de la API mediante la API de REST de API Gateway ](api-gateway-documenting-api-quick-start-publishing.md) + [ # Importar la documentación de API ](api-gateway-documenting-api-quick-start-import-export.md) + [ # Controlar el acceso a la documentación de la API en API Gateway ](api-gateway-documenting-api-content-provision-and-consumption.md) # Representación de la documentación de la API en API Gateway La documentación de la API de API Gateway consta de piezas de documentación individuales asociadas a entidades de API específicas que incluyen la API, el recurso, el método, la solicitud, la respuesta, los parámetros de mensaje (como ruta, consulta, encabezado), así como autorizadores y modelos. En API Gateway, una pieza de documentación se representa mediante un recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html). La documentación de la API en su conjunto se representa mediante la colección [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationParts.html). Documentar una API implica crear instancias de `DocumentationPart`, añadirlas a la colección `DocumentationParts` y mantener versiones de las piezas de la documentación a medida que evolucione la API. **Topics** + [ ## Piezas de la documentación ](#api-gateway-documenting-api-content-representation-documentation-parts) + [ ## Versiones de la documentación ](#api-gateway-documenting-api-content-representation-documentation-versions) ## Piezas de la documentación Un recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) es un objeto JSON que almacena el contenido de la documentación aplicable a una entidad de API determinada. Esto incluye cualquier contenido UTF-8 y todos los idiomas de localización principales de la documentación. Su campo `properties` incluye el contenido de la documentación como un mapa de pares de clave-valor. Su propiedad `location` identifica la entidad de API asociada. La forma de un mapa de contenido lo determina usted, el desarrollador de la API. El valor del par de clave-valor puede ser una cadena, un número, un valor booleano, un objeto o una matriz. La forma del objeto `location` depende del tipo de entidad de destino. El recurso `DocumentationPart` admite la herencia de contenido: el contenido de documentación de una entidad de API se aplica a los elementos secundarios de dicha entidad. Para obtener más información sobre la definición de entidades secundarias y la herencia de contenido, consulte [Heredar contenido de una entidad de API de especificación más general](#api-gateway-documenting-api-content-inheritance). ### Ubicación de una pieza de documentación La propiedad [location](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#location) de una instancia [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) identifica una entidad de API a la que se aplica el contenido asociado. La entidad de la API puede ser un recurso de la API de REST de API Gateway, como [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html), [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html), [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html), [Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) o [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html). La entidad también puede ser un parámetro de mensaje, como un parámetro de ruta URL, un parámetro de cadena de consulta, un parámetro de encabezado de solicitud o respuesta, una solicitud o cuerpo de respuesta o un código de estado de respuesta. Para especificar una entidad de API, establezca el atributo [type](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#type) del objeto `location` en `API`, `AUTHORIZER`, `MODEL`, `RESOURCE`, `METHOD`, `PATH_PARAMETER`, `QUERY_PARAMETER`, `REQUEST_HEADER`, `REQUEST_BODY`, `RESPONSE`, `RESPONSE_HEADER` o `RESPONSE_BODY`. En función del `type` de una entidad de API, puede especificar otros atributos `location`, incluidos [method](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#method), [name](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#name), [path](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#path) y [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#statusCode). No todos estos atributos son válidos para una determinada entidad de API. Por ejemplo, `type`, `path`, `name` y `statusCode` son atributos válidos de la entidad `RESPONSE`; solo `type` y `path` son atributos de ubicación válidos de la entidad `RESOURCE`. Es un error incluir un campo no válido en el atributo `location` de un recurso `DocumentationPart` para una determinada entidad de API. No todos los campos `location` válidos son obligatorios. Por ejemplo, `type` es el campo `location` válido y obligatorio para todas las entidades de API. Sin embargo, `method`, `path` y `statusCode` son válidos, pero no son atributos obligatorios para la entidad `RESPONSE`. Cuando no se especifica explícitamente, un campo `location` válido asume el valor predeterminado. El valor `path` predeterminado es `/`, es decir, el recurso raíz de una API. El valor predeterminado de `method` o `statusCode` es `*`, que indica cualquier método o valores de código de estado, respectivamente. ### Contenido de una pieza de documentación El valor `properties` está codificado como una cadena JSON. El valor `properties` contiene la información que elija para satisfacer sus necesidades de documentación. Por ejemplo, a continuación se muestra un mapa de contenido válido: ``` { "info": { "description": "My first API with Amazon API Gateway." }, "x-custom-info" : "My custom info, recognized by OpenAPI.", "my-info" : "My custom info not recognized by OpenAPI." } ``` Aunque API Gateway admite cualquier cadena JSON válida como mapa de contenido, los atributos de contenido se tratan atendiendo a dos categorías: los que OpenAPI reconoce y los que no. En el ejemplo anterior, `info`, `description` y `x-custom-info` son atributos reconocidos por OpenAPI como un objeto, propiedad o extensión estándar de OpenAPI. En cambio, `my-info` no es compatible con la especificación de OpenAPI. API Gateway propaga los atributos de contenido compatibles con OpenAPI a las definiciones de entidad de API de las instancias de `DocumentationPart` asociadas. API Gateway no propaga los atributos de contenido no compatibles a las definiciones de entidad de API. Veamos otro ejemplo; aquí `DocumentationPart` es el destino de una entidad `Resource`: ``` { "location" : { "type" : "RESOURCE", "path": "/pets" }, "properties" : { "summary" : "The /pets resource represents a collection of pets in PetStore.", "description": "... a child resource under the root...", } } ``` Tanto `type` como `path` son campos válidos para identificar el destino del tipo `RESOURCE`. Para el recurso raíz (`/`), puede omitir el campo `path`. ``` { "location" : { "type" : "RESOURCE" }, "properties" : { "description" : "The root resource with the default path specification." } } ``` Es el mismo que la siguiente instancia de `DocumentationPart`: ``` { "location" : { "type" : "RESOURCE", "path": "/" }, "properties" : { "description" : "The root resource with an explicit path specification" } } ``` ### Heredar contenido de una entidad de API de especificaciones más generales El valor predeterminado de un campo `location` opcional proporciona una descripción de los patrones de una entidad de API. Con el valor predeterminado en el objeto `location`, puede añadir una descripción general en el mapa `properties` a una instancia de `DocumentationPart` con este tipo de patrón `location`. API Gateway extrae los atributos de documentación de OpenAPI aplicables de `DocumentationPart` de la entidad de API genérica y los inserta en una entidad de API específica con los campos `location` con valores que coinciden con el patrón `location` general o con el valor exacto, a menos que la entidad especificada ya tenga una instancia de `DocumentationPart` asociada. Este comportamiento se denomina también "herencia de contenido de una entidad de API de especificaciones más generales". La herencia de contenido no se aplica a determinados tipos de entidades de API. Consulte la siguiente tabla para obtener más detalles. Cuando una entidad de API coincide con más de un patrón de ubicación de `DocumentationPart`, la entidad heredará la pieza de documentación con los campos de ubicación que tengan mayor prioridad y sean más específicos. El orden de prioridad es `path` > `statusCode`. Para la correspondencia con el campo `path`, API Gateway elige la entidad con el valor de ruta más específico. En la siguiente tabla se muestra esto con algunos ejemplos. | Caso | `path` | `statusCode` | `name` | Remarks | | --- | --- | --- | --- | --- | | 1 | /pets | \$1 | id | La documentación asociada a este patrón de ubicación la heredarán las entidades que coincidan con el patrón de ubicación. | | 2 | /pets | 200 | id | La documentación asociada a este patrón de ubicación la heredarán las entidades que coincidan con el patrón de ubicación cuando coincidan tanto Caso 1 como Caso 2, ya que Caso 2 es más específico que Caso 1. | | 3 | /pets/petId | \$1 | id | La documentación asociada a este patrón de ubicación la heredarán las entidades que coincidan con el patrón de ubicación cuando los tres casos coincidan, ya que Caso 3 tiene más prioridad que Caso 2 y es más específico que Caso 1. | Este es otro ejemplo en el que se compara una instancia de `DocumentationPart` más genérica con una más específica. El siguiente mensaje de error general `"Invalid request error"` se inserta en las definiciones de OpenAPI de las respuestas de error `400`, a menos que se invalide. ``` { "location" : { "type" : "RESPONSE", "statusCode": "400" }, "properties" : { "description" : "Invalid request error." }" } ``` Con la siguiente invalidación, las respuestas `400` a cualquier método del recurso `/pets` tienen una descripción de `"Invalid petId specified"` en su lugar. ``` { "location" : { "type" : "RESPONSE", "path": "/pets", "statusCode": "400" }, "properties" : "{ "description" : "Invalid petId specified." }" } ``` ### Campos de ubicación válidos de `DocumentationPart` En la siguiente tabla, se muestran los campos válidos y obligatorios, así como los valores predeterminados aplicables, de un recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) asociado a un tipo de entidades de API determinado. | Entidad de API | Campos de ubicación válidos | Campos de ubicación obligatorios | Valores de campo predeterminados | Contenido heredable | | --- | --- | --- | --- | --- | | [API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) | 
{
    "location": {
        "type": "API" 
    }, 
    ... 
}
| type | N/A | No | | [Recurso](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) | 
{ 
    "location": { 
        "type": "RESOURCE", 
        "path": "resource_path" 
    }, 
    ... 
}
| type | El valor predeterminado de path es /. | No | | [Método](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) | 
{ 
    "location": { 
        "type": "METHOD", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}
| type | Los valores predeterminados de path y method son / y \$1, respectivamente. | Sí, buscando coincidencias de path por prefijo y buscando coincidencias del elemento method de cualquier valor. | | Parámetros de consulta | 
{ 
    "location": { 
        "type": "QUERY_PARAMETER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "query_parameter_name" 
    }, 
    ... 
}
| type | Los valores predeterminados de path y method son / y \$1, respectivamente. | Sí, buscando coincidencias de path por prefijo y buscando coincidencias del elemento method por los valores exactos. | | Cuerpo de la solicitud | 
{ 
    "location": { 
        "type": "REQUEST_BODY", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}
| type | Los valores predeterminados de path y method son / y \$1, respectivamente. | Sí, buscando coincidencias de path por prefijo y buscando coincidencias del elemento method por los valores exactos. | | Parámetro de encabezado de solicitud | 
{ 
    "location": { 
        "type": "REQUEST_HEADER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "header_name" 
    }, 
    ... 
}
| type, name | Los valores predeterminados de path y method son / y \$1, respectivamente. | Sí, buscando coincidencias de path por prefijo y buscando coincidencias del elemento method por los valores exactos. | | Parámetros de ruta de solicitud | 
{ 
    "location": { 
        "type": "PATH_PARAMETER", 
        "path": "resource/{path_parameter_name}", 
        "method": "HTTP_verb",
        "name": "path_parameter_name" 
    }, 
    ... 
}
| type, name | Los valores predeterminados de path y method son / y \$1, respectivamente. | Sí, buscando coincidencias de path por prefijo y buscando coincidencias del elemento method por los valores exactos. | | Respuesta | 
{ 
    "location": { 
        "type": "RESPONSE", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}
| type | Los valores predeterminados de path, method y statusCode son /, \$1 y \$1, respectivamente. | Sí, buscando coincidencias de path por prefijo y buscando coincidencias de los elementos method y statusCode por los valores exactos. | | Encabezado de respuesta | 
{ 
    "location": { 
        "type": "RESPONSE_HEADER", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code", 
        "name": "header_name" 
    }, 
    ... 
}
| type, name | Los valores predeterminados de path, method y statusCode son /, \$1 y \$1, respectivamente. | Sí, buscando coincidencias de path por prefijo y buscando coincidencias de los elementos method y statusCode por los valores exactos. | | Cuerpo de respuesta | 
{ 
    "location": { 
        "type": "RESPONSE_BODY", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}
| type | Los valores predeterminados de path, method y statusCode son /, \$1 y \$1, respectivamente. | Sí, buscando coincidencias de path por prefijo y buscando coincidencias de los elementos method y statusCode por los valores exactos. | | [Autorizador](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) | 
{ 
    "location": { 
        "type": "AUTHORIZER", 
        "name": "authorizer_name" 
    }, 
    ... 
}
| type | N/A | No | | [Modelo](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) | 
{ 
    "location": { 
        "type": "MODEL", 
        "name": "model_name" 
    }, 
    ... 
}
| type | N/A | No | ## Versiones de la documentación Una versión de la documentación es una instantánea de la colección [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) de una API, que está etiquetada con un identificador de versión. Publicar la documentación de una API implica crear una versión de documentación, asociarla a una etapa de la API y exportar esa versión específica de la etapa de la documentación de la API a un archivo de OpenAPI externo. En API Gateway, una instantánea de documentación se representa como un recurso [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html). Cuando se actualiza una API, se crean nuevas versiones de la API. En API Gateway, todas las versiones de la documentación se mantienen mediante la colección [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html). # Proceso de documentación de una API mediante la consola API Gateway En esta sección se describe cómo crear y actualizar piezas de documentación de una API mediante la consola de API Gateway. Un requisito previo para crear y editar la documentación de una API es que ya debe haber creado 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-document-api-add-document-part-for-api-entity-with-console) + [ ## Documentar una entidad `RESOURCE` ](#api-gateway-document-api-add-document-part-for-resource-entity-with-console) + [ ## Documentar una entidad `METHOD` ](#api-gateway-document-api-add-document-part-for-method-entity-with-console) + [ ## Documentar una entidad `QUERY_PARAMETER` ](#api-gateway-document-api-add-document-part-for-request-query-entity-with-console) + [ ## Documentar una entidad `PATH_PARAMETER` ](#api-gateway-document-api-add-document-part-for-path-parameter-entity-with-console) + [ ## Documentar una entidad `REQUEST_HEADER` ](#api-gateway-document-api-add-document-part-for-request-header-entity-with-console) + [ ## Documentar una entidad `REQUEST_BODY` ](#api-gateway-document-api-add-document-part-for-request-body-entity-with-console) + [ ## Documentar una entidad `RESPONSE` ](#api-gateway-document-api-add-document-part-for-response-with-console) + [ ## Documentar una entidad `RESPONSE_HEADER` ](#api-gateway-document-api-add-document-part-for-response-header-entity-with-console) + [ ## Documentar una entidad `RESPONSE_BODY` ](#api-gateway-document-api-add-document-part-for-response-body-entity-with-console) + [ ## Documentar una entidad `MODEL` ](#api-gateway-document-api-add-document-part-for-model-entity-with-console) + [ ## Documentar una entidad `AUTHORIZER` ](#api-gateway-document-api-add-document-part-for-authorizer-entity-with-console) ## Documentar la entidad `API` Para agregar una nueva pieza de documentación para la entidad `API`, haga lo siguiente: 1. En el panel de navegación principal, elija **Documentación** y, a continuación, elija **Crear pieza de documentación**. 1. En **Tipo de documentación**, seleccione **API**. Si no se creó una pieza de documentación para la `API`, verá el editor del mapa `properties` de la pieza de documentación. Especifique el siguiente mapa `properties` en el editor de texto. ``` { "info": { "description": "Your first API Gateway API.", "contact": { "name": "John Doe", "email": "john.doe@api.com" } } } ``` **nota** No es necesario codificar el mapa `properties` en una cadena JSON. La consola de API Gateway representa el objeto JSON en una cadena automáticamente. 1. Elija **Crear pieza de documentación**. Para agregar una nueva pieza de documentación para la entidad `API` en el panel **Recursos**, haga lo siguiente: 1. En el panel de navegación principal, elija **Recursos**. 1. Elija el menú **Acciones API** y, a continuación, elija **Actualizar la documentación de la API**. ![\[Editar la documentación de la entidad de API en la consola de API Gateway\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/document-api-entity-using-new-console.png) Para editar una pieza existente de la documentación, haga lo siguiente: 1. En el panel **Documentación**, elija la pestaña **Recursos y métodos**. 1. Seleccione el nombre de la API y, a continuación, en la tarjeta de API, elija **Editar**. ## Documentar una entidad `RESOURCE` Para agregar una nueva pieza de documentación para una entidad `RESOURCE`, haga lo siguiente: 1. En el panel de navegación principal, elija **Documentación** y, a continuación, elija **Crear pieza de documentación**. 1. En **Tipo de documentación**, seleccione **API**. 1. En **Ruta**, ingrese una ruta. 1. Ingrese una descripción en el editor de texto, por ejemplo: ``` { "description": "The PetStore's root resource." } ``` 1. Elija **Crear pieza de documentación**. Puede crear documentación para un recurso que no figure en la lista. 1. Si es necesario, repita estos pasos para agregar o editar otra pieza de documentación. Para agregar una nueva pieza de documentación para una entidad `RESOURCE` en el panel **Recursos**, haga lo siguiente: 1. En el panel de navegación principal, elija **Recursos**. 1. Elija el recurso y, a continuación, elija **Actualizar documentación**. ![\[Editar la documentación de la entidad de recurso en la consola de API Gateway\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/document-resource-entity-using-new-console.png) Para editar una pieza existente de la documentación, haga lo siguiente: 1. En el panel **Documentación**, elija la pestaña **Recursos y métodos**. 1. Seleccione el recurso que contiene la pieza de documentación y, a continuación, elija **Editar**. ## Documentar una entidad `METHOD` Para agregar una nueva pieza de documentación para una entidad `METHOD`, haga lo siguiente: 1. En el panel de navegación principal, elija **Documentación** y, a continuación, elija **Crear pieza de documentación**. 1. En **Tipo de documentación**, seleccione **Método**. 1. En **Ruta**, ingrese una ruta. 1. En **Método**, seleccione un verbo HTTP. 1. Ingrese una descripción en el editor de texto, por ejemplo: ``` { "tags" : [ "pets" ], "summary" : "List all pets" } ``` 1. Elija **Crear pieza de documentación**. Puede crear documentación para un método que no figure en la lista. 1. Si es necesario, repita estos pasos para agregar o editar otra pieza de documentación. Para agregar una nueva pieza de documentación para una entidad `METHOD` en el panel **Recursos**, haga lo siguiente: 1. En el panel de navegación principal, elija **Recursos**. 1. Elija el método y, a continuación, elija **Actualizar documentación**. ![\[Editar la documentación de la entidad de método en la consola de API Gateway\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/document-method-entity-using-new-console.png) Para editar una pieza existente de la documentación, haga lo siguiente: 1. En el panel **Documentación**, elija la pestaña **Recursos y métodos**. 1. Puede seleccionar el método o seleccionar el recurso que contiene el método y, a continuación, utilizar la barra de búsqueda para buscar y seleccionar la pieza de documentación. 1. Seleccione **Editar**. ## Documentar una entidad `QUERY_PARAMETER` Para agregar una nueva pieza de documentación para una entidad `QUERY_PARAMETER`, haga lo siguiente: 1. En el panel de navegación principal, elija **Documentación** y, a continuación, elija **Crear pieza de documentación**. 1. En **Tipo de documentación**, seleccione **Parámetro de consulta**. 1. En **Ruta**, ingrese una ruta. 1. En **Método**, seleccione un verbo HTTP. 1. En **Nombre**, ingrese un nombre. 1. Ingrese una descripción en el editor de texto. 1. Elija **Crear pieza de documentación**. Puede crear documentación para un parámetro de consulta que no figure en la lista. 1. Si es necesario, repita estos pasos para agregar o editar otra pieza de documentación. Para editar una pieza existente de la documentación, haga lo siguiente: 1. En el panel **Documentación**, elija la pestaña **Recursos y métodos**. 1. Puede seleccionar el parámetro de consulta o seleccionar el recurso que contiene el parámetro de consulta y, a continuación, utilizar la barra de búsqueda para buscar y seleccionar la pieza de documentación. 1. Seleccione **Editar**. ## Documentar una entidad `PATH_PARAMETER` Para agregar una nueva pieza de documentación para una entidad `PATH_PARAMETER`, haga lo siguiente: 1. En el panel de navegación principal, elija **Documentación** y, a continuación, elija **Crear pieza de documentación**. 1. En **Tipo de documentación**, seleccione el **Parámetro de ruta**. 1. En **Ruta**, ingrese una ruta. 1. En **Método**, seleccione un verbo HTTP. 1. En **Nombre**, ingrese un nombre. 1. Ingrese una descripción en el editor de texto. 1. Elija **Crear pieza de documentación**. Puede crear documentación para un parámetro de ruta que no figure en la lista. 1. Si es necesario, repita estos pasos para agregar o editar otra pieza de documentación. Para editar una pieza existente de la documentación, haga lo siguiente: 1. En el panel **Documentación**, elija la pestaña **Recursos y métodos**. 1. Puede seleccionar el parámetro de ruta o seleccionar el recurso que contiene el parámetro de ruta y, a continuación, utilizar la barra de búsqueda para buscar y seleccionar la pieza de documentación. 1. Seleccione **Editar**. ## Documentar una entidad `REQUEST_HEADER` Para agregar una nueva pieza de documentación para una entidad `REQUEST_HEADER`, haga lo siguiente: 1. En el panel de navegación principal, elija **Documentación** y, a continuación, elija **Crear pieza de documentación**. 1. En **Tipo de documentación**, seleccione **Encabezado de solicitud**. 1. En **Ruta**, ingrese una ruta para el encabezado de la solicitud. 1. En **Método**, seleccione un verbo HTTP. 1. En **Nombre**, ingrese un nombre. 1. Ingrese una descripción en el editor de texto. 1. Elija **Crear pieza de documentación**. Puede crear documentación para un encabezado de solicitud que no figure en la lista. 1. Si es necesario, repita estos pasos para agregar o editar otra pieza de documentación. Para editar una pieza existente de la documentación, haga lo siguiente: 1. En el panel **Documentación**, elija la pestaña **Recursos y métodos**. 1. Puede seleccionar el encabezado de solicitud o seleccionar el recurso que contiene el encabezado de solicitud y, a continuación, utilizar la barra de búsqueda para buscar y seleccionar la pieza de documentación. 1. Seleccione **Editar**. ## Documentar una entidad `REQUEST_BODY` Para agregar una nueva pieza de documentación para una entidad `REQUEST_BODY`, haga lo siguiente: 1. En el panel de navegación principal, elija **Documentación** y, a continuación, elija **Crear pieza de documentación**. 1. En **Tipo de documentación**, seleccione **Cuerpo de la solicitud**. 1. En **Ruta**, ingrese una ruta para el cuerpo de la solicitud. 1. En **Método**, seleccione un verbo HTTP. 1. Ingrese una descripción en el editor de texto. 1. Elija **Crear pieza de documentación**. Puede crear documentación para un cuerpo de solicitud que no figure en la lista. 1. Si es necesario, repita estos pasos para agregar o editar otra pieza de documentación. Para editar una pieza existente de la documentación, haga lo siguiente: 1. En el panel **Documentación**, elija la pestaña **Recursos y métodos**. 1. Puede seleccionar el cuerpo de la solicitud o seleccionar el recurso que contiene el cuerpo de la solicitud y, a continuación, utilizar la barra de búsqueda para buscar y seleccionar la pieza de documentación. 1. Seleccione **Editar**. ## Documentar una entidad `RESPONSE` Para agregar una nueva pieza de documentación para una entidad `RESPONSE`, haga lo siguiente: 1. En el panel de navegación principal, elija **Documentación** y, a continuación, elija **Crear pieza de documentación**. 1. En **Tipo de documentación**, seleccione **Respuesta (código de estado)**. 1. En **Ruta**, ingrese una ruta para la respuesta. 1. En **Método**, seleccione un verbo HTTP. 1. En **Código de estado**, ingrese un código de estado HTTP. 1. Ingrese una descripción en el editor de texto. 1. Elija **Crear pieza de documentación**. Puede crear documentación para un código de estado de respuesta que no figure en la lista. 1. Si es necesario, repita estos pasos para agregar o editar otra pieza de documentación. Para editar una pieza existente de la documentación, haga lo siguiente: 1. En el panel **Documentación**, elija la pestaña **Recursos y métodos**. 1. Puede seleccionar el código de estado de la respuesta o seleccionar el recurso que contiene el código de estado de la respuesta y, a continuación, utilizar la barra de búsqueda para buscar y seleccionar la pieza de documentación. 1. Seleccione **Editar**. ## Documentar una entidad `RESPONSE_HEADER` Para agregar una nueva pieza de documentación para una entidad `RESPONSE_HEADER`, haga lo siguiente: 1. En el panel de navegación principal, elija **Documentación** y, a continuación, elija **Crear pieza de documentación**. 1. En **Tipo de documentación**, seleccione **Encabezado de respuesta**. 1. En **Ruta**, ingrese una ruta para el encabezado de la respuesta. 1. En **Método**, seleccione un verbo HTTP. 1. En **Código de estado**, ingrese un código de estado HTTP. 1. Ingrese una descripción en el editor de texto. 1. Elija **Crear pieza de documentación**. Puede crear documentación para un encabezado de respuesta que no figure en la lista. 1. Si es necesario, repita estos pasos para agregar o editar otra pieza de documentación. Para editar una pieza existente de la documentación, haga lo siguiente: 1. En el panel **Documentación**, elija la pestaña **Recursos y métodos**. 1. Puede seleccionar el encabezado de la respuesta o seleccionar el recurso que contiene el encabezado de la respuesta y, a continuación, utilizar la barra de búsqueda para buscar y seleccionar la pieza de documentación. 1. Seleccione **Editar**. ## Documentar una entidad `RESPONSE_BODY` Para agregar una nueva pieza de documentación para una entidad `RESPONSE_BODY`, haga lo siguiente: 1. En el panel de navegación principal, elija **Documentación** y, a continuación, elija **Crear pieza de documentación**. 1. En **Tipo de documentación**, seleccione **Cuerpo de respuesta**. 1. En **Ruta**, ingrese una ruta para el cuerpo de la respuesta. 1. En **Método**, seleccione un verbo HTTP. 1. En **Código de estado**, ingrese un código de estado HTTP. 1. Ingrese una descripción en el editor de texto. 1. Elija **Crear pieza de documentación**. Puede crear documentación para un cuerpo de respuesta que no figure en la lista. 1. Si es necesario, repita estos pasos para agregar o editar otra pieza de documentación. Para editar una pieza existente de la documentación, haga lo siguiente: 1. En el panel **Documentación**, elija la pestaña **Recursos y métodos**. 1. Puede seleccionar el cuerpo de la respuesta o seleccionar el recurso que contiene el cuerpo de la respuesta y, a continuación, utilizar la barra de búsqueda para buscar y seleccionar la pieza de documentación. 1. Seleccione **Editar**. ## 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 una nueva pieza de documentación para una entidad `MODEL`, haga lo siguiente: 1. En el panel de navegación principal, elija **Documentación** y, a continuación, elija **Crear pieza de documentación**. 1. En **Tipo de documentación**, seleccione **Modelo**. 1. En **Nombre**, ingrese un nombre para el modelo. 1. Ingrese una descripción en el editor de texto. 1. Elija **Crear pieza de documentación**. Puede crear documentación para modelos que no figuren en la lista. 1. Si es necesario, repita estos pasos para añadir o editar una pieza de documentación para otros modelos. Para agregar una nueva pieza de documentación para una entidad `MODEL` en el panel **Modelos**, haga lo siguiente: 1. En el panel de navegación principal, elija **Modelos**. 1. Elija el modelo y, a continuación, elija **Actualizar documentación**. ![\[Editar la documentación de la entidad de modelo en la consola de API Gateway\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/document-model-entity-using-new-console.png) Para editar una pieza existente de la documentación, haga lo siguiente: 1. En el panel **Documentación**, elija la pestaña **Modelos**. 1. Utilice la barra de búsqueda o seleccione el modelo y, a continuación, elija **Editar**. ## Documentar una entidad `AUTHORIZER` Para agregar una nueva pieza de documentación para una entidad `AUTHORIZER`, haga lo siguiente: 1. En el panel de navegación principal, elija **Documentación** y, a continuación, elija **Crear pieza de documentación**. 1. En **Tipo de documentación**, seleccione **Autorizador**. 1. En **Nombre**, ingrese el nombre del autorizador. 1. Ingrese una descripción en el editor de texto. Especifique un valor para el campo válido de `location` para el autorizador. 1. Elija **Crear pieza de documentación**. Puede crear documentación para autorizadores que no figuren en la lista. 1. Si es necesario, repita estos pasos para añadir o editar una pieza de documentación para otros autorizadores. Para editar una pieza existente de la documentación, haga lo siguiente: 1. En el panel **Documentación**, elija la pestaña **Autorizadores**. 1. Utilice la barra de búsqueda o seleccione el autorizador y, a continuación, elija **Editar**. # Publicación de documentación de la API mediante la consola de API Gateway El procedimiento siguiente describe cómo publicar una versión de la documentación. **Para publicar una versión de la documentación mediante la consola de API Gateway** 1. En el panel de navegación principal, elija **Documentación**. 1. Elija **Publicar documentación**. 1. Configure la publicación: 1. En **Etapa**, seleccione una etapa. 1. En **Versión**, ingrese un identificador de versión, por ejemplo, `1.0.0`. 1. (Opcional) En **Description (Descripción)**, introduzca una descripción. 1. Elija **Publish**. Ahora puede empezar a descargar la documentación publicada exportando la documentación a un archivo de OpenAPI externo. Para obtener más información, consulte [Exportación de una API REST desde API Gateway](api-gateway-export-api.md). # 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. # 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). # Importar la documentación de API De igual modo que para importar definiciones de entidad de API, puede importar piezas de documentación de un archivo de OpenAPI externo a una API mediante API Gateway. Las piezas de documentación que se van a importar se especifican en la extensión [Objeto x-amazon-apigateway-documentation](api-gateway-swagger-extensions-documentation.md) en un archivo de definición de OpenAPI válido. La importación de la documentación no modifica las definiciones de entidad de API existentes. Tiene la opción de combinar las piezas de documentación recién especificadas en piezas de documentación existentes en API Gateway o de sobrescribir las piezas de documentación existentes. En el modo `MERGE`, una nueva pieza de documentación definida en el archivo de OpenAPI se añade a la colección `DocumentationParts` de la API. Si ya existe un elemento `DocumentationPart` importado, el atributo importado reemplaza al existente si los dos son diferentes. Todos los demás atributos de documentación existentes permanecen tal como están. En el modo `OVERWRITE`, toda la colección `DocumentationParts` se reemplaza de acuerdo con el archivo de definición de OpenAPI importado. ## Importar piezas de documentación mediante la API de REST de API Gateway Para importar la documentación de API mediante la API de REST de API Gateway, llame a la operación [documentationpart:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportDocumentationParts.html). En el siguiente ejemplo, se muestra cómo sobrescribir las piezas de documentación existentes de una API con un único método `GET / `, que devuelve una respuesta `200 OK` si se ejecuta correctamente. ------ #### [ OpenAPI 3.0 ] ``` PUT /restapis//documentation/parts&mode=overwrite&failonwarnings=true Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "openapi": "3.0.0", "info": { "description": "description", "version": "1", "title": "doc" }, "paths": { "/": { "get": { "description": "Method description.", "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } } } } } }, "x-amazon-apigateway-documentation": { "version": "1.0.3", "documentationParts": [ { "location": { "type": "API" }, "properties": { "description": "API description", "info": { "description": "API info description 4", "version": "API info version 3" } } }, { "location": { "type": "METHOD", "method": "GET" }, "properties": { "description": "Method description." } }, { "location": { "type": "MODEL", "name": "Empty" }, "properties": { "title": "Empty Schema" } }, { "location": { "type": "RESPONSE", "method": "GET", "statusCode": "200" }, "properties": { "description": "200 response" } } ] }, "servers": [ { "url": "/" } ], "components": { "schemas": { "Empty": { "type": "object", "title": "Empty Schema" } } } } ``` ------ #### [ OpenAPI 2.0 ] ``` PUT /restapis//documentation/parts&mode=overwrite&failonwarnings=true Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "swagger": "2.0", "info": { "description": "description", "version": "1", "title": "doc" }, "host": "", "basePath": "/", "schemes": [ "https" ], "paths": { "/": { "get": { "description": "Method description.", "produces": [ "application/json" ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } } } } } }, "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } }, "x-amazon-apigateway-documentation": { "version": "1.0.3", "documentationParts": [ { "location": { "type": "API" }, "properties": { "description": "API description", "info": { "description": "API info description 4", "version": "API info version 3" } } }, { "location": { "type": "METHOD", "method": "GET" }, "properties": { "description": "Method description." } }, { "location": { "type": "MODEL", "name": "Empty" }, "properties": { "title": "Empty Schema" } }, { "location": { "type": "RESPONSE", "method": "GET", "statusCode": "200" }, "properties": { "description": "200 response" } } ] } } ``` ------ Cuando se ejecuta correctamente, esta solicitud devuelve una respuesta 200 OK que contiene el elemento `DocumentationPartId` importado en la carga. ``` { "ids": [ "kg3mth", "796rtf", "zhek4p", "5ukm9s" ] } ``` Además, también puede llamar a [restapi:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportRestApi.html) o [restapi:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutRestApi.html), proporcionando las piezas de documentación en el objeto `x-amazon-apigateway-documentation` como parte del archivo de OpenAPI de entrada de la definición de la API. Para excluir piezas de documentación de la importación de API, establezca `ignore=documentation` en los parámetros de consulta de la solicitud. ## Importar piezas de documentación mediante la consola de API Gateway Las siguientes instrucciones describen cómo importar piezas de documentación. **Para utilizar la consola para importar piezas de documentación de una API desde un archivo externo** 1. En el panel de navegación principal, elija **Documentación**. 1. Seleccione **Importar**. 1. Si ya tiene documentación, seleccione **Sobrescribir** o **Fusionar** la nueva documentación. 1. Elija **Seleccionar archivo** para cargar un archivo de una unidad, o ingrese el contenido del archivo en la vista de archivos. Para ver un ejemplo, consulte la carga de la solicitud de ejemplo de [Importar piezas de documentación mediante la API de REST de API Gateway](#api-gateway-importing-api-with-swagger-file-using-rest-api). 1. Elija cómo gestionar las advertencias durante la importación. Seleccione **Error en advertencias** o **Ignorar advertencias**. Para obtener más información, consulte [Errores y advertencias al importar la API a API Gateway](api-gateway-import-api-errors-warnings.md). 1. Seleccione **Importar**. # Controlar el acceso a la documentación de la API en API Gateway Si tiene un equipo de documentación dedicado a escribir y editar la documentación de la API, puede configurar permisos de acceso distintos para los desarrolladores (para el desarrollo de la API) y para los redactores o editores (para el desarrollo de contenido). Esto resulta especialmente útil para un proveedor externo encargado de crear la documentación por usted. Para otorgar al equipo de documentación acceso para crear, actualizar y publicar la documentación de la API, puede asignar un rol de IAM al equipo de documentación con la siguiente política de IAM, donde *account\$1id* es el ID de la cuenta de AWS del equipo de documentación. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "StmtDocPartsAddEditViewDelete", "Effect": "Allow", "Action": [ "apigateway:GET", "apigateway:PUT", "apigateway:POST", "apigateway:PATCH", "apigateway:DELETE" ], "Resource": [ "arn:aws:apigateway:us-east-1:111111111111:/restapis/*/documentation/*" ] } ] } ``` ------ Para obtener información sobre la configuración de permisos para obtener acceso a recursos de API Gateway, consulte [Cómo funciona Amazon API Gateway con IAM](security_iam_service-with-iam.md).