Rappresentazione della API documentazione in Gateway API

APILa API documentazione del gateway è costituita da singole parti della documentazione associate a API entità specifiche che includono risorseAPI, metodi, richieste, risposte, parametri del messaggio (ad esempio, path, query, header), nonché autorizzatori e modelli.

In API Gateway, una parte della documentazione è rappresentata da una DocumentationPartrisorsa. La API documentazione nel suo insieme è rappresentata dalla DocumentationPartsraccolta.

La documentazione API implica la creazione di DocumentationPart istanze, l'aggiunta alla DocumentationParts raccolta e la manutenzione delle versioni delle parti della documentazione man mano API che la documentazione si evolve.

Parti della documentazione

Una DocumentationPartrisorsa è un JSON oggetto che memorizza il contenuto della documentazione applicabile a una singola entità. API Il campo properties contiene il contenuto della documentazione sotto forma di mappa di coppie chiave-valore. locationLa sua proprietà identifica l'APIentità associata.

La forma di una mappa dei contenuti è determinata da te, lo API sviluppatore. Il valore di una coppia chiave-valore può essere una stringa, un numero, un booleano, un oggetto o una matrice. La forma dell'oggetto location dipende dal tipo di entità di destinazione.

La DocumentationPart risorsa supporta l'ereditarietà dei contenuti: il contenuto della documentazione di un'APIentità è applicabile ai figli di tale API entità. Per ulteriori informazioni sulla definizione di entità secondarie e sull'ereditarietà del contenuto, consulta Ereditare il contenuto da un'APIentità con specifiche più generali.

Posizione di una parte della documentazione

La proprietà location di un'DocumentationPartistanza identifica un'APIentità a cui si applica il contenuto associato. L'APIentità può essere una REST API risorsa API Gateway, ad esempio Resource RestApi, Method MethodResponse, Authorizer o Model. L'entità può anche essere un parametro di messaggio, ad esempio un parametro URL path, un parametro della stringa di query, un parametro di intestazione della richiesta o della risposta, un corpo della richiesta o della risposta o un codice di stato della risposta.

Per specificare un'APIentità, imposta l'attributo type dell'locationoggetto in modo che sia uno di API AUTHORIZERMODEL,RESOURCE,METHOD,PATH_PARAMETER,QUERY_PARAMETER,REQUEST_HEADER,REQUEST_BODY, RESPONSERESPONSE_HEADER, oRESPONSE_BODY.

A seconda type dell'APIentità, potete specificare altri location attributi, tra cui metodo, nome, percorso e statusCode. Non tutti questi attributi sono validi per una determinata API entità. Ad esempio, type, path, name e statusCode sono attributi validi dell'entità RESPONSE, solo type e path sono attributi di posizione validi dell'entità RESOURCE. È un errore includere un campo non valido nel campo location DocumentationPart di una determinata API entità.

Non tutti i campi location validi sono obbligatori. Ad esempio, type è sia il location campo valido che quello obbligatorio di tutte le API entità. Tuttavia, method, path e statusCode sono attributi validi ma non obbligatori per l'entità RESPONSE. Se non è specificato esplicitamente, un campo location valido assume il valore predefinito. Il path valore predefinito è/, ad esempio, la risorsa principale di unAPI. Il valore predefinito di method o statusCode è *, ossia qualsiasi valore di metodo o codice di stato, rispettivamente.

Contenuto di una parte della documentazione

Il properties valore è codificato come JSON stringa. Il valore properties contiene tutte le informazioni che hai scelto per soddisfare i tuoi requisiti di documentazione. Ad esempio, la seguente è una mappa di contenuti valida:

{
  "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."
}

Sebbene API Gateway accetti qualsiasi JSON stringa valida come mappa del contenuto, gli attributi di contenuto vengono trattati come due categorie: quelli che possono essere riconosciuti da Open API e quelli che non possono essere riconosciuti. Nell'esempio precedente, infodescription, e x-custom-info sono riconosciuti da Open API come API oggetto, proprietà o estensione Open standard. Al contrario, non my-info è conforme alla specifica Open. API APIGateway propaga gli attributi API di contenuto conformi a Open nelle definizioni di API entità dalle istanze associate. DocumentationPart APIGateway non propaga gli attributi di contenuto non conformi nelle definizioni delle entità. API

Per un altro esempio, ecco un DocumentationPart mirato per un'entità 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...",
    }
}

Qui, type e path sono entrambi campi validi per l'identificazione della destinazione del tipo RESOURCE. Per la risorsa radice (/), puoi omettere il campo path.

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

È equivalente alla seguente istanza di DocumentationPart:

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

Eredita il contenuto da un'APIentità con specifiche più generali

Il valore predefinito di un location campo opzionale fornisce una descrizione modellata di un'APIentità. Usando il valore predefinito dell'oggetto location, puoi aggiungere una descrizione generale nella mappa di properties a un'istanza di DocumentationPart con questo tipo di modello location. APIGateway estrae gli attributi DocumentationPart di Open API documentation applicabili dall'APIentità generica e li inserisce in API un'entità specifica i cui location campi corrispondono allo location schema generale o al valore esatto, a meno che l'entità specifica non abbia già un'DocumentationPartistanza associata. Questo comportamento è noto anche come ereditarietà del contenuto da un'APIentità con specifiche più generali.

L'ereditarietà dei contenuti non si applica a determinati tipi di entità. API Per informazioni dettagliate, consulta la tabella seguente.

Quando un'APIentità corrisponde a più di uno schema DocumentationPart di localizzazione, erediterà la parte relativa alla documentazione con i campi di localizzazione con la precedenza e le specificità più elevate. L'ordine di precedenza è path > statusCode. Per la corrispondenza con il path campo, API Gateway sceglie l'entità con il valore di percorso più specifico. La seguente tabella mostra questo comportamento con alcuni esempi.

Caso	path	statusCode	name	Remarks
1	/pets	*	id	La documentazione associata a questo modello di posizione verrà ereditata dalle entità che corrispondono al modello di posizione.
2	/pets	200	id	La documentazione associata a questo modello di posizione verrà ereditata dalle entità che corrispondono al modello di posizione in caso di corrispondenza con il caso 1 e il caso 2, in quanto il caso 2 è più specifico del caso 1.
3	/pets/petId	*	id	La documentazione associata a questo modello di posizione verrà ereditata dalle entità che corrispondono al modello di posizione quando i casi 1, 2 e 3 sono corrispondenti, poiché il caso 3 ha una precedenza maggiore rispetto al caso 2 ed è più specifico del caso 1.

Ecco un altro esempio per contrapporre un'istanza di DocumentationPart più generica con una più specifica. Il seguente messaggio di errore generale di "Invalid request error" viene inserito nelle API definizioni Open delle risposte di 400 errore, a meno che non venga sovrascritto.

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

Con la seguente sostituzione, l'errore 400 che risponde ai metodi della risorsa /pets ha la descrizione "Invalid petId specified".

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

Campi di posizione di valid DocumentationPart

La tabella seguente mostra i campi validi e obbligatori, nonché i valori predefiniti applicabili di una DocumentationPartrisorsa associata a un determinato tipo di entità. API

Entità API	Campi di posizione validi	Campi di posizione obbligatori	Valori dei campi predefiniti	Contenuto ereditabile
API	{ "location": { "type": "API" }, ... }	type	N/D	No
Resource (Risorsa)	{ "location": { "type": "RESOURCE", "path": "resource_path" }, ... }	type	Il valore predefinito di path è /.	No
Metodo	{ "location": { "type": "METHOD", "path": "resource_path", "method": "http_verb" }, ... }	type	I valori predefiniti di path e method sono / e *, rispettivamente.	Sì, con corrispondenza di path per il prefisso e corrispondenza di method per qualsiasi valore.
Parametro di query	{ "location": { "type": "QUERY_PARAMETER", "path": "resource_path", "method": "HTTP_verb", "name": "query_parameter_name" }, ... }	type	I valori predefiniti di path e method sono / e *, rispettivamente.	Sì, con corrispondenza di path per il prefisso e corrispondenza di method per i valori esatti.
Corpo di richiesta	{ "location": { "type": "REQUEST_BODY", "path": "resource_path", "method": "http_verb" }, ... }	type	I valori predefiniti di path e method sono / e *, rispettivamente.	Sì, con corrispondenza di path per il prefisso e corrispondenza di method per i valori esatti.
Parametro di intestazione di richiesta	{ "location": { "type": "REQUEST_HEADER", "path": "resource_path", "method": "HTTP_verb", "name": "header_name" }, ... }	type, name	I valori predefiniti di path e method sono / e *, rispettivamente.	Sì, con corrispondenza di path per il prefisso e corrispondenza di method per i valori esatti.
Parametro di percorso richiesta	{ "location": { "type": "PATH_PARAMETER", "path": "resource/{path_parameter_name}", "method": "HTTP_verb", "name": "path_parameter_name" }, ... }	type, name	I valori predefiniti di path e method sono / e *, rispettivamente.	Sì, con corrispondenza di path per il prefisso e corrispondenza di method per i valori esatti.
Risposta	{ "location": { "type": "RESPONSE", "path": "resource_path", "method": "http_verb", "statusCode": "status_code" }, ... }	type	I valori predefiniti di path, method e statusCode sono /, * e *, rispettivamente.	Sì, con corrispondenza di path per il prefisso e corrispondenza di method e statusCode per i valori esatti.
Intestazione della risposta	{ "location": { "type": "RESPONSE_HEADER", "path": "resource_path", "method": "http_verb", "statusCode": "status_code", "name": "header_name" }, ... }	type, name	I valori predefiniti di path, method e statusCode sono /, * e *, rispettivamente.	Sì, con corrispondenza di path per il prefisso e corrispondenza di method e statusCode per i valori esatti.
Corpo di risposta	{ "location": { "type": "RESPONSE_BODY", "path": "resource_path", "method": "http_verb", "statusCode": "status_code" }, ... }	type	I valori predefiniti di path, method e statusCode sono /, * e *, rispettivamente.	Sì, con corrispondenza di path per il prefisso e corrispondenza di method e statusCode per i valori esatti.
Authorizer	{ "location": { "type": "AUTHORIZER", "name": "authorizer_name" }, ... }	type	N/A	No
Modello	{ "location": { "type": "MODEL", "name": "model_name" }, ... }	type	N/A	No

Versioni della documentazione

Una versione della documentazione è un'istantanea della DocumentationPartsraccolta di un file API ed è contrassegnata con un identificatore di versione. La pubblicazione della documentazione di un API implica la creazione di una versione della documentazione, l'associazione a una API fase e l'esportazione di quella versione della API documentazione specifica per la fase in un file Open esterno. API In API Gateway, un'istantanea della documentazione è rappresentata come una risorsa. DocumentationVersion

Quando si aggiorna unAPI, si creano nuove versioni diAPI. In API Gateway, si mantengono tutte le versioni della documentazione utilizzando la DocumentationVersionsraccolta.