Proceso de documentación de una API mediante la consola API Gateway - Amazon API Gateway
Documentar la entidad APIDocumentar una entidad RESOURCEDocumentar una entidad METHODDocumentar una entidad QUERY_PARAMETERDocumentar una entidad PATH_PARAMETER Documentar una entidad REQUEST_HEADERDocumentar una entidad REQUEST_BODYDocumentar una entidad RESPONSEDocumentar una entidad RESPONSE_HEADERDocumentar una entidad RESPONSE_BODYDocumentar una entidad MODELDocumentar una entidad AUTHORIZER

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

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.

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

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

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

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.

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

  2. En Tipo de documentación, seleccione API.

  3. En Ruta, ingrese una ruta.

  4. Ingrese una descripción en el editor de texto, por ejemplo:

    {
    "description": "The PetStore's root resource."
}

  5. Elija Crear pieza de documentación. Puede crear documentación para un recurso que no figure en la lista.

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

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

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.

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

  2. En Tipo de documentación, seleccione Método.

  3. En Ruta, ingrese una ruta.

  4. En Método, seleccione un verbo HTTP.

  5. Ingrese una descripción en el editor de texto, por ejemplo:

    {
  "tags" : [ "pets" ],
  "summary" : "List all pets"
}

  6. Elija Crear pieza de documentación. Puede crear documentación para un método que no figure en la lista.

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

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

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.

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

  3. Elija 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.

  2. En Tipo de documentación, seleccione Parámetro de consulta.

  3. En Ruta, ingrese una ruta.

  4. En Método, seleccione un verbo HTTP.

  5. En Nombre, ingrese un nombre.

  6. Ingrese una descripción en el editor de texto.

  7. Elija Crear pieza de documentación. Puede crear documentación para un parámetro de consulta que no figure en la lista.

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

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

  3. Elija 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.

  2. En Tipo de documentación, seleccione el Parámetro de ruta.

  3. En Ruta, ingrese una ruta.

  4. En Método, seleccione un verbo HTTP.

  5. En Nombre, ingrese un nombre.

  6. Ingrese una descripción en el editor de texto.

  7. Elija Crear pieza de documentación. Puede crear documentación para un parámetro de ruta que no figure en la lista.

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

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

  3. Elija 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.

  2. En Tipo de documentación, seleccione Encabezado de solicitud.

  3. En Ruta, ingrese una ruta para el encabezado de la solicitud.

  4. En Método, seleccione un verbo HTTP.

  5. En Nombre, ingrese un nombre.

  6. Ingrese una descripción en el editor de texto.

  7. Elija Crear pieza de documentación. Puede crear documentación para un encabezado de solicitud que no figure en la lista.

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

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

  3. Elija 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.

  2. En Tipo de documentación, seleccione Cuerpo de la solicitud.

  3. En Ruta, ingrese una ruta para el cuerpo de la solicitud.

  4. En Método, seleccione un verbo HTTP.

  5. Ingrese una descripción en el editor de texto.

  6. Elija Crear pieza de documentación. Puede crear documentación para un cuerpo de solicitud que no figure en la lista.

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

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

  3. Elija 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.

  2. En Tipo de documentación, seleccione Respuesta (código de estado).

  3. En Ruta, ingrese una ruta para la respuesta.

  4. En Método, seleccione un verbo HTTP.

  5. En Código de estado, ingrese un código de estado HTTP.

  6. Ingrese una descripción en el editor de texto.

  7. Elija Crear pieza de documentación. Puede crear documentación para un código de estado de respuesta que no figure en la lista.

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

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

  3. Elija 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.

  2. En Tipo de documentación, seleccione Encabezado de respuesta.

  3. En Ruta, ingrese una ruta para el encabezado de la respuesta.

  4. En Método, seleccione un verbo HTTP.

  5. En Código de estado, ingrese un código de estado HTTP.

  6. Ingrese una descripción en el editor de texto.

  7. Elija Crear pieza de documentación. Puede crear documentación para un encabezado de respuesta que no figure en la lista.

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

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

  3. Elija 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.

  2. En Tipo de documentación, seleccione Cuerpo de respuesta.

  3. En Ruta, ingrese una ruta para el cuerpo de la respuesta.

  4. En Método, seleccione un verbo HTTP.

  5. En Código de estado, ingrese un código de estado HTTP.

  6. Ingrese una descripción en el editor de texto.

  7. Elija Crear pieza de documentación. Puede crear documentación para un cuerpo de respuesta que no figure en la lista.

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

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

  3. Elija 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.

  2. En Tipo de documentación, seleccione Modelo.

  3. En Nombre, ingrese un nombre para el modelo.

  4. Ingrese una descripción en el editor de texto.

  5. Elija Crear pieza de documentación. Puede crear documentación para modelos que no figuren en la lista.

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

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

Para editar una pieza existente de la documentación, haga lo siguiente:

  1. En el panel Documentación, elija la pestaña Modelos.

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

  2. En Tipo de documentación, seleccione Autorizador.

  3. En Nombre, ingrese el nombre del autorizador.

  4. Ingrese una descripción en el editor de texto. Especifique un valor para el campo válido de location para el autorizador.

  5. Elija Crear pieza de documentación. Puede crear documentación para autorizadores que no figuren en la lista.

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

  2. Utilice la barra de búsqueda o seleccione el autorizador y, a continuación, elija Editar.