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