# Proceso de documentación de una API mediante la consola API Gateway
<a name="api-gateway-documenting-api-quick-start-with-console"></a>

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`
<a name="api-gateway-document-api-add-document-part-for-api-entity-with-console"></a>

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`
<a name="api-gateway-document-api-add-document-part-for-resource-entity-with-console"></a>

 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`
<a name="api-gateway-document-api-add-document-part-for-method-entity-with-console"></a>

 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.  Elija **Edit (Edición de)**.

## Documentar una entidad `QUERY_PARAMETER`
<a name="api-gateway-document-api-add-document-part-for-request-query-entity-with-console"></a>

 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. Elija **Edit (Edición de)**.

## Documentar una entidad `PATH_PARAMETER`
<a name="api-gateway-document-api-add-document-part-for-path-parameter-entity-with-console"></a>

 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. Elija **Edit (Edición de)**.

## Documentar una entidad `REQUEST_HEADER`
<a name="api-gateway-document-api-add-document-part-for-request-header-entity-with-console"></a>

 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. Elija **Edit (Edición de)**.

## Documentar una entidad `REQUEST_BODY`
<a name="api-gateway-document-api-add-document-part-for-request-body-entity-with-console"></a>

 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. Elija **Edit (Edición de)**.

## Documentar una entidad `RESPONSE`
<a name="api-gateway-document-api-add-document-part-for-response-with-console"></a>

 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. Elija **Edit (Edición de)**.

## Documentar una entidad `RESPONSE_HEADER`
<a name="api-gateway-document-api-add-document-part-for-response-header-entity-with-console"></a>

 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. Elija **Edit (Edición de)**.

## Documentar una entidad `RESPONSE_BODY`
<a name="api-gateway-document-api-add-document-part-for-response-body-entity-with-console"></a>

 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. Elija **Edit (Edición de)**.

## Documentar una entidad `MODEL`
<a name="api-gateway-document-api-add-document-part-for-model-entity-with-console"></a>

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`
<a name="api-gateway-document-api-add-document-part-for-authorizer-entity-with-console"></a>

 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**.