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. La documentación de la API en su conjunto se representa mediante la colección DocumentationParts.

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.

Piezas de la documentación

Un recurso DocumentationPart es un objeto JSON que almacena el contenido de la documentación aplicable a una entidad de API determinada. 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.

Ubicación de una pieza de documentación

La propiedad location de una instancia DocumentationPart 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, Resource, Method, MethodResponse, Authorizer o Model. 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 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, name, path y 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.

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 asociado a un tipo de entidades de API determinado.

{
    "location": {
        "type": "API" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "RESOURCE", 
        "path": "resource_path" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "METHOD", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "QUERY_PARAMETER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "query_parameter_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "REQUEST_BODY", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "REQUEST_HEADER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "header_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "PATH_PARAMETER", 
        "path": "resource/{path_parameter_name}", 
        "method": "HTTP_verb",
        "name": "path_parameter_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "RESPONSE", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "RESPONSE_HEADER", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code", 
        "name": "header_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "RESPONSE_BODY", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "AUTHORIZER", 
        "name": "authorizer_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "MODEL", 
        "name": "model_name" 
    }, 
    ... 
}

Versiones de la documentación

Una versión de la documentación es una instantánea de la colección DocumentationParts 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.

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.