Rappresentazione della documentazione dell'API in API Gateway

La documentazione dell'API in API Gateway è costituita da singole parti associate a specifiche entità API che includono API, risorsa, metodo, richiesta, risposta parametri del messaggio (ad esempio, percorso, query, intestazione), nonché autorizzazioni e modelli.

In API Gateway, una parte della documentazione è rappresentata da una DocumentationPartrisorsa. L'intera documentazione dell'API è rappresentata dalla DocumentationPartsraccolta.

La documentazione di un'API implica la creazione di istanze di DocumentationPart, aggiungendole alla raccolta DocumentationParts e mantenendo le versioni delle parti della documentazione man mano che l'API evolve.

Parti della documentazione

Una DocumentationPartrisorsa è un oggetto JSON 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. La proprietà location identifica l'entità API associata.

La forma della mappa di contenuti è determinata da te, lo sviluppatore dell'API. 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 risorsa DocumentationPart supporta l'ereditarietà del contenuto: il contenuto della documentazione di un'entità API è applicabile agli elementi figlio dell'entità API. Per ulteriori informazioni sulla definizione di entità figlio ed ereditarietà del contenuto, consulta Ereditare il contenuto da un'entità API di più specifiche generali.

Posizione di una parte della documentazione

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

Per specificare un'entità API, impostare l'attributo type dell'oggetto location su uno dei seguenti valori API, AUTHORIZER, MODEL, RESOURCE, METHOD, PATH_PARAMETER, QUERY_PARAMETER, REQUEST_HEADER, REQUEST_BODY, RESPONSE, RESPONSE_HEADER o RESPONSE_BODY.

A seconda dell'attributo type di un'entità API, è possibile specificare altri attributi location, tra cui method, name, path e statusCode. Non tutti questi attributi sono validi per una determinata entità API. 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. Non è corretto includere un campo non valido nell'attributo location di DocumentationPart per una determinata entità API.

Non tutti i campi location validi sono obbligatori. Ad esempio, type è il campo location valido e obbligatorio di tutte le entità API. 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 valore predefinito di path è /, vale a dire la risorsa radice di un'API. Il valore predefinito di method o statusCode è *, ossia qualsiasi valore di metodo o codice di stato, rispettivamente.

Contenuto di una parte della documentazione

Il valore di properties è codificato come stringa JSON. 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."
}

Anche se API Gateway accetta qualsiasi stringa JSON valida come mappa di contenuti, gli attributi del contenuto sono trattati come due categorie: quelli che possono e quelli che non possono essere riconosciuti da OpenAPI. Nell'esempio precedente, info, description e x-custom-info sono riconosciuti da OpenAPI come oggetto, proprietà o estensione OpenAPI standard. Di contro, my-info non è conforme alle specifiche OpenAPI. API Gateway propaga gli attributi di contenuto conformi a OpenAPI nelle definizioni di entità API delle istanze di DocumentationPart associate. API Gateway non propaga gli attributi di contenuto non conformi nelle definizioni di 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"
    }
} 

Ereditare il contenuto da un'entità API di specifiche più generali

Il valore predefinito di un campo location facoltativo fornisce una descrizione di modello di un'entità API. 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. API Gateway estrae gli attributi della documentazione OpenAPI applicabili da DocumentationPart dell'entità API generica e li inserisce in un'entità API specifica con i campi location corrispondenti al modello location generale o corrispondenti al valore esatto, a meno che l'entità specifica non disponga già di un'istanza DocumentationPart associata. Questo comportamento è anche noto come ereditarietà del contenuto da un'entità API con specifiche più generali.

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

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

Ecco un altro esempio per contrapporre un'istanza di DocumentationPart più generica con una più specifica. Il seguente messaggio di errore generale "Invalid request error" è inserito nelle definizioni di OpenAPI delle risposte dell'errore 400, se non sostituite.

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

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

Versioni della documentazione

Una versione della documentazione è un'istantanea della DocumentationPartsraccolta di un'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 con una fase API e l'esportazione della versione specifica della fase della documentazione dell'API in un file OpenAPI esterno. In API Gateway, un'istantanea della documentazione è rappresentata come una DocumentationVersionrisorsa.

Quando aggiorni un'API, crei nuove versioni dell'API. In API Gateway, gestisci tutte le versioni della documentazione utilizzando la DocumentationVersionsraccolta.