Representação da documentação da API no API Gateway

A documentação de API do API Gateway consiste em partes de documentação individuais associadas a entidades de API específicas que incluem API, recurso, método, solicitação, resposta, parâmetros de mensagem (ou seja, caminho, consulta, cabeçalho), bem como autorizadores e modelos.

No API Gateway, uma parte de documentação é representada por um recurso DocumentationPart. A documentação da API como um todo é representada pela coleção DocumentationParts.

Documentar uma API envolve criar instâncias de DocumentationPart, adicioná-las à coleção DocumentationParts e manter versões das partes de documentação à medida que a sua API evolui.

Partes da documentação

Um recurso DocumentationPart é um objeto JSON que armazena o conteúdo da documentação aplicável a uma entidade da API individual. Seu campo properties contém o conteúdo da documentação como um mapa de pares de chave/valor. Sua propriedade location identifica a entidade de API associada.

A forma de um mapa de conteúdo é determinada por você, o desenvolvedor da API. O valor de um par de chave/valor pode ser uma string, número, booliano, objeto ou matriz. A forma do objeto location depende do tipo de entidade alvo.

O recurso DocumentationPart oferece suporte para herança de conteúdo: o conteúdo da documentação de uma entidade de API é aplicável aos filhos dessa entidade de API. Para obter mais informações sobre a definição de entidades filho e herança de conteúdo, consulte Herdar conteúdo de uma entidade de API com especificação mais geral.

Localização de uma parte de documentação

A propriedade location de uma instância de DocumentationPart identifica uma entidade de API à qual o conteúdo associado se aplica. A entidade de API pode ser um recurso de API REST do API Gateway, como RestApi, Resource, Method, MethodResponse, Authorizer ou Model. Ela também pode ser um parâmetro de mensagem, como um parâmetro de caminho de URL, um parâmetro de string de consulta, um parâmetro de cabeçalho de solicitação ou resposta, um corpo de solicitação ou resposta ou um código de status de resposta.

Para especificar uma entidade da API, defina o atributo type do objeto location como um dos seguintes: API, AUTHORIZER, MODEL, RESOURCE, METHOD, PATH_PARAMETER, QUERY_PARAMETER, REQUEST_HEADER, REQUEST_BODY, RESPONSE, RESPONSE_HEADER ou RESPONSE_BODY.

Dependendo do type de uma entidade da API, você pode especificar outros atributos de location, incluindo method, name, path e statusCode. Nem todos esses atributos são válidos para uma determinada entidade de API. Por exemplo, type, path, name e statusCode são atributos válidos da entidade RESPONSE; apenas type e path são atributos de localização válidos da entidade RESOURCE. É um erro incluir um campo inválido no location de um DocumentationPart para uma determinada entidade de API.

Nem todos os campos válidos de location são necessários. Por exemplo, type é o campo location tanto válido quanto obrigatório de todas as entidades de API. No entanto, method, path e statusCode são atributos válidos, mas não obrigatórios, para a entidade RESPONSE. Quando não explicitamente especificado, um campo location válido assume seu valor padrão. O valor de path padrão é /, ou seja, o recurso raiz de uma API. O valor padrão de method, ou statusCode, é *, significando qualquer valor de método ou código de status, respectivamente.

Conteúdo de uma parte da documentação

O valor de properties é codificado como uma string JSON. O valor de properties contém qualquer informação que você escolher para atender às suas necessidades de documentação. Por exemplo, o seguinte é um mapa de conteúdo 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."
}

Embora o API Gateway aceite qualquer string JSON válida como o mapa de conteúdo, os atributos de conteúdo são tratados como duas categorias: aqueles que podem ser reconhecidos pelo OpenAPI e aqueles que não podem. No exemplo anterior, info, description e x-custom-info são reconhecidos pelo OpenAPI como um objeto, uma propriedade ou uma extensão padrão do OpenAPI. Em contraste, my-info não é compatível com a especificação OpenAPI. O API Gateway propaga atributos de conteúdo compatíveis com OpenAPI para as definições de entidades de API das instâncias DocumentationPart associadas. O API Gateway não propaga os atributos de conteúdo não compatíveis nas definições de entidades de API.

Como outro exemplo, aqui está uma DocumentationPart direcionada para uma entidade 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...",
    }
}

Aqui, tanto type quanto path são campos válidos para identificar o destino do tipo RESOURCE. Para o recurso de raiz (/), você pode omitir o campo path.

{
    "location" : {
        "type" : "RESOURCE"
    },
    "properties" : {
        "description" : "The root resource with the default path specification."
    }
}

Isso equivale à seguinte instância de DocumentationPart:

{
    "location" : {
        "type" : "RESOURCE",
        "path": "/"
    },
    "properties" : {
        "description" : "The root resource with an explicit path specification"
    }
} 

Herdar conteúdo de uma entidade de API com especificações mais gerais

O valor padrão de um campo location opcional fornece uma descrição padronizada de uma entidade de API. Usando o valor padrão no objeto location, é possível adicionar uma descrição geral no mapa properties a uma instância de DocumentationPart com esse tipo de padrão de location. O API Gateway extrai os atributos da documentação do OpenAPI aplicáveis de DocumentationPart da entidade de API genérica e os injeta em uma entidade de API específica com os campos location correspondentes ao padrão location geral ou correspondentes ao valor exato, a menos que a entidade específica já tenha uma instância de DocumentationPart associada a ela. Esse comportamento também é conhecido como herança de conteúdo de uma entidade de API de especificações mais gerais.

A herança de conteúdo não se aplica a determinados tipos de entidade de API. Consulte a tabela a seguir para obter detalhes.

Quando uma entidade de API corresponder ao padrão de localização de DocumentationPart, ela herdará a parte de documentação com os campos de localização de maior precedência e especificidade. A ordem de precedência é path > statusCode. Para correspondência com o campo path, o API Gateway escolhe a entidade com o valor do caminho mais específico. A tabela a seguir mostra isso com alguns exemplos.

Caso	path	statusCode	name	Observações
1	/pets	*	id	A documentação associada a esse padrão de localização será herdada por entidades que corresponderem ao padrão de localização.
2	/pets	200	id	A documentação associada a esse padrão de localização será herdada por entidades que corresponderem ao padrão de localização quando tanto o Caso 1 quanto o Caso 2 forem correspondidos, pois o Caso 2 é mais específico do que o Caso 1.
3	/pets/petId	*	id	A documentação associada a esse padrão de localização será herdada por entidades que corresponderem ao padrão de localização quando os Casos 1, 2 e 3 forem correspondidos, pois o Caso 3 tem precedência maior do que o Caso 2 e é mais específico do que o Caso 1.

Veja a seguir outro exemplo para contrastar uma instância mais genérica de DocumentationPart com uma mais específica. A seguinte mensagem de erro geral "Invalid request error" será injetada nas definições do OpenAPI das respostas de erro 400, a menos que ela seja substituída.

{
    "location" : {
        "type" : "RESPONSE",
        "statusCode": "400"
    },
    "properties" : {
        "description" : "Invalid request error."
    }"
}

Com a seguinte substituição, as respostas 400 a qualquer método no recurso /pets têm uma descrição de "Invalid petId specified" em vez disso.

{
    "location" : {
        "type" : "RESPONSE",
        "path": "/pets",
        "statusCode": "400"
    },
    "properties" : "{
        "description" : "Invalid petId specified."
    }"
}

Campos de localização válidos de DocumentationPart

A seguinte tabela mostra os campos válidos e necessários, bem como valores padrão aplicáveis de um recurso DocumentationPart que está associado a um determinado tipo de entidade de API.

Entidade de API	Campos de localização válidos	Campos de localização obrigatórios	Valores de campo padrão	Conteúdo herdável
API	{ "location": { "type": "API" }, ... }	type	N/D	Não
Recurso	{ "location": { "type": "RESOURCE", "path": "resource_path" }, ... }	type	O valor padrão de path é /.	Não
Método	{ "location": { "type": "METHOD", "path": "resource_path", "method": "http_verb" }, ... }	type	Os valores padrão de path e method são / e *, respectivamente.	Sim, correspondendo path por prefixo e correspondendo method de quaisquer valores.
Parâmetro de consulta	{ "location": { "type": "QUERY_PARAMETER", "path": "resource_path", "method": "HTTP_verb", "name": "query_parameter_name" }, ... }	type	Os valores padrão de path e method são / e *, respectivamente.	Sim, correspondendo path por prefixo e correspondendo method por valores exatos.
Corpo da solicitação	{ "location": { "type": "REQUEST_BODY", "path": "resource_path", "method": "http_verb" }, ... }	type	Os valores padrão de path e method são / e *, respectivamente.	Sim, correspondendo path por prefixo e correspondendo method por valores exatos.
Parâmetro do cabeçalho da solicitação	{ "location": { "type": "REQUEST_HEADER", "path": "resource_path", "method": "HTTP_verb", "name": "header_name" }, ... }	type, name	Os valores padrão de path e method são / e *, respectivamente.	Sim, correspondendo path por prefixo e correspondendo method por valores exatos.
Parâmetro do caminho da solicitação	{ "location": { "type": "PATH_PARAMETER", "path": "resource/{path_parameter_name}", "method": "HTTP_verb", "name": "path_parameter_name" }, ... }	type, name	Os valores padrão de path e method são / e *, respectivamente.	Sim, correspondendo path por prefixo e correspondendo method por valores exatos.
Resposta	{ "location": { "type": "RESPONSE", "path": "resource_path", "method": "http_verb", "statusCode": "status_code" }, ... }	type	Os valores padrão de path, method e statusCode são /, * e *, respectivamente.	Sim, correspondendo path por prefixo e correspondendo method e statusCode por valores exatos.
Cabeçalho da resposta	{ "location": { "type": "RESPONSE_HEADER", "path": "resource_path", "method": "http_verb", "statusCode": "status_code", "name": "header_name" }, ... }	type, name	Os valores padrão de path, method e statusCode são /, * e *, respectivamente.	Sim, correspondendo path por prefixo e correspondendo method e statusCode por valores exatos.
Corpo da resposta	{ "location": { "type": "RESPONSE_BODY", "path": "resource_path", "method": "http_verb", "statusCode": "status_code" }, ... }	type	Os valores padrão de path, method e statusCode são /, * e *, respectivamente.	Sim, correspondendo path por prefixo e correspondendo method e statusCode por valores exatos.
Autorizador	{ "location": { "type": "AUTHORIZER", "name": "authorizer_name" }, ... }	type	N/D	Não
Modelo	{ "location": { "type": "MODEL", "name": "model_name" }, ... }	type	N/D	Não

Versões da documentação

Uma versão de documentação é um snapshot da coleção DocumentationParts de uma API e é marcada com um identificador de versão. Publicar a documentação de uma API envolve criar uma versão da documentação, associá-la a um estágio de API e exportar essa versão específica de estágio da documentação da API para um arquivo do OpenAPI externo. No API Gateway, um snapshot de documentação é representado como um recurso DocumentationVersion.

À medida que você atualiza uma API, novas versões dela são criadas. No API Gateway, todas as versões da documentação são mantidas usando a coleção DocumentationVersions.