Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Documentazione per REST APIs in API Gateway Per aiutare i clienti a comprendere e utilizzare la tua API, è fondamentale documentarla. Per aiutarti a documentare l'API, API Gateway ti consente di aggiungere e aggiornare il contenuto della guida per le singole entità API come parte integrante del processo di sviluppo dell'API. API Gateway memorizza il contenuto di origine e ti consente di archiviare diverse versioni della documentazione. Puoi associare una versione della documentazione a una fase API, esportare uno snapshot di documentazione specifico della fase in un file OpenAPI esterno e distribuire il file come pubblicazione della documentazione. Per documentare la tua API, puoi chiamare l'[API REST di API Gateway](https://docs.aws.amazon.com/apigateway/latest/api/), utilizzare una delle [AWS SDKs](https://aws.amazon.com/developer/tools/), utilizzare [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/apigateway/)for API Gateway o utilizzare la console API Gateway. Inoltre, puoi importare o esportare le parti della documentazione definite in un file OpenAPI esterno. Per condividere la documentazione API con gli sviluppatori, puoi utilizzare un portale per sviluppatori. Per un esempio, consulta [Integrazione ReadMe con API Gateway per mantenere aggiornato il tuo Developer Hub o [Come semplificare lo sviluppo di API su Amazon API Gateway Using SmartBear SwaggerHub](https://aws.amazon.com/blogs/apn/how-to-streamline-api-development-on-amazon-api-gateway-using-smartbear-swaggerhub/)](https://aws.amazon.com/blogs/apn/integrating-readme-with-amazon-api-gateway-to-keep-your-developer-hub-up-to-date/) sul blog AWS Partner Network (APN). **Topics** + [Rappresentazione della documentazione dell'API in API Gateway](api-gateway-documenting-api-content-representation.md) + [Documentare un'API utilizzando la console API Gateway](api-gateway-documenting-api-quick-start-with-console.md) + [Pubblicare la documentazione dell'API utilizzando la console API Gateway](apigateway-documenting-api-with-console.md) + [Documentare un'API utilizzando l'API REST di API Gateway](api-gateway-documenting-api-quick-start-with-restapi.md) + [Pubblicare la documentazione dell'API utilizzando l'API REST di API Gateway](api-gateway-documenting-api-quick-start-publishing.md) + [Importare la documentazione dell'API](api-gateway-documenting-api-quick-start-import-export.md) + [Controllo dell'accesso alla documentazione dell'API in Gateway API](api-gateway-documenting-api-content-provision-and-consumption.md) # 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 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa. L'intera documentazione dell'API è rappresentata dalla [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationParts.html)raccolta. 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. **Topics** + [Parti della documentazione](#api-gateway-documenting-api-content-representation-documentation-parts) + [Versioni della documentazione](#api-gateway-documenting-api-content-representation-documentation-versions) ## Parti della documentazione Una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa è un oggetto JSON che memorizza il contenuto della documentazione applicabile a una singola entità API. Sono inclusi contenuti UTF-8 e tutte le principali lingue di localizzazione per la documentazione. 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](#api-gateway-documenting-api-content-inheritance). ### Posizione di una parte della documentazione La proprietà [location](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#location) di un'[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)istanza 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](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html), [Method [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.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). 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](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#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](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) e [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#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. | Caso | `path` | `statusCode` | `name` | Remarks | | --- | --- | --- | --- | --- | | 1 | /pets | \$1 | 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 | \$1 | 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 `"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 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa 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](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) | 
{
    "location": {
        "type": "API" 
    }, 
    ... 
}
| type | N/A | No | | [Risorsa](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) | 
{ 
    "location": { 
        "type": "RESOURCE", 
        "path": "resource_path" 
    }, 
    ... 
}
| type | Il valore predefinito di path è /. | No | | [Metodo](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) | 
{ 
    "location": { 
        "type": "METHOD", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}
| type | I valori predefiniti di path e method sono / e \$1, 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 \$1, 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 \$1, 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 \$1, 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 \$1, 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 /, \$1 e \$1, 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 /, \$1 e \$1, 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 /, \$1 e \$1, rispettivamente. | Sì, con corrispondenza di path per il prefisso e corrispondenza di method e statusCode per i valori esatti. | | [Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) | 
{ 
    "location": { 
        "type": "AUTHORIZER", 
        "name": "authorizer_name" 
    }, 
    ... 
}
| type | N/A | No | | [Modello](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) | 
{ 
    "location": { 
        "type": "MODEL", 
        "name": "model_name" 
    }, 
    ... 
}
| type | N/A | No | ## Versioni della documentazione Una versione della documentazione è un'istantanea della [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)raccolta 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 [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)risorsa. Quando aggiorni un'API, crei nuove versioni dell'API. In API Gateway, gestisci tutte le versioni della documentazione utilizzando la [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)raccolta. # Documentare un'API utilizzando la console API Gateway In questa sezione, viene descritto come creare e gestire la parti della documentazione di un'API tramite la console API Gateway. Un prerequisito per la creazione e la modifica della documentazione di un'API è che l'API deve essere già stata creata. In questa sezione, utilizziamo l'[PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets)API come esempio. Per creare un'API utilizzando la console API Gateway, seguire le istruzioni in [Tutorial: creazione di un'API REST mediante l'importazione di un esempio](api-gateway-create-api-from-example.md). **Topics** + [Documentare l'entità `API`](#api-gateway-document-api-add-document-part-for-api-entity-with-console) + [Documentare un'entità `RESOURCE`](#api-gateway-document-api-add-document-part-for-resource-entity-with-console) + [Documentare un'entità `METHOD`](#api-gateway-document-api-add-document-part-for-method-entity-with-console) + [Documentare un'entità `QUERY_PARAMETER`](#api-gateway-document-api-add-document-part-for-request-query-entity-with-console) + [Documentare un'entità `PATH_PARAMETER`](#api-gateway-document-api-add-document-part-for-path-parameter-entity-with-console) + [Documentare un'entità `REQUEST_HEADER`](#api-gateway-document-api-add-document-part-for-request-header-entity-with-console) + [Documentare un'entità `REQUEST_BODY`](#api-gateway-document-api-add-document-part-for-request-body-entity-with-console) + [Documentare un'entità `RESPONSE`](#api-gateway-document-api-add-document-part-for-response-with-console) + [Documentare un'entità `RESPONSE_HEADER`](#api-gateway-document-api-add-document-part-for-response-header-entity-with-console) + [Documentare un'entità `RESPONSE_BODY`](#api-gateway-document-api-add-document-part-for-response-body-entity-with-console) + [Documentare un'entità `MODEL`](#api-gateway-document-api-add-document-part-for-model-entity-with-console) + [Documentare un'entità `AUTHORIZER`](#api-gateway-document-api-add-document-part-for-authorizer-entity-with-console) ## Documentare l'entità `API` Per aggiungere una nuova parte della documentazione per l'entità `API`, procedi come segue: 1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**. 1. Per **Tipo di documentazione** seleziona **API**. Se una parte della documentazione non è stata creata per l'`API`, viene visualizzato l'editor della mappa di `properties` della parte della documentazione. Inserisci la seguente mappa di `properties` nell'editor di testo. ``` { "info": { "description": "Your first API Gateway API.", "contact": { "name": "John Doe", "email": "john.doe@api.com" } } } ``` **Nota** Non è necessario codificare la mappa `properties` in una stringa JSON. La console API Gateway trasforma in stringa l'oggetto JSON per tuo conto. 1. Scegli **Crea parte della documentazione**. Per aggiungere una nuova parte della documentazione per l'entità `API` nel riquadro **Risorse**, procedi come segue: 1. Nel riquadro di navigazione principale scegli **Risorse**. 1. Scegli il menu **Operazioni API**, quindi seleziona **Aggiorna documentazione dell'API**. ![\[Modificare la documentazione per l'entità API nella console API Gateway\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/document-api-entity-using-new-console.png) Per modificare una parte della documentazione esistente, procedi come segue: 1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**. 1. Seleziona il nome dell'API, quindi nella scheda dell'API scegli **Modifica**. ## Documentare un'entità `RESOURCE` Per aggiungere una nuova parte della documentazione per un'entità `RESOURCE`, procedi come segue: 1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**. 1. Per **Tipo di documentazione** seleziona **Risorsa**. 1. Per **Percorso** inserisci un percorso. 1. Immetti una descrizione nell'editor di testo, ad esempio: ``` { "description": "The PetStore's root resource." } ``` 1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per una risorsa non elencata. 1. Se necessario, ripeti queste fasi per aggiungere o modificare un'altra parte della documentazione. Per aggiungere una nuova parte della documentazione per un'entità `RESOURCE` nel riquadro **Risorse**, procedi come segue: 1. Nel riquadro di navigazione principale scegli **Risorse**. 1. Scegli la risorsa, quindi seleziona **Aggiorna documentazione**. ![\[Modifica della documentazione per l'entità risorsa nella console Gateway API\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/document-resource-entity-using-new-console.png) Per modificare una parte della documentazione esistente, procedi come segue: 1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**. 1. Seleziona la risorsa contenente la parte della documentazione, quindi scegli **Modifica**. ## Documentare un'entità `METHOD` Per aggiungere una nuova parte della documentazione per un'entità `METHOD`, procedi come segue: 1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**. 1. Per **Tipo di documentazione** seleziona **Metodo**. 1. Per **Percorso** inserisci un percorso. 1. Per **Metodo** seleziona un verbo HTTP. 1. Immetti una descrizione nell'editor di testo, ad esempio: ``` { "tags" : [ "pets" ], "summary" : "List all pets" } ``` 1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per un metodo non elencato. 1. Se necessario, ripeti queste fasi per aggiungere o modificare un'altra parte della documentazione. Per aggiungere una nuova parte della documentazione per un'entità `METHOD` nel riquadro **Risorse**, procedi come segue: 1. Nel riquadro di navigazione principale scegli **Risorse**. 1. Scegli il metodo, quindi seleziona **Aggiorna documentazione**. ![\[Modifica della documentazione per l'entità metodo nella console Gateway API\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/document-method-entity-using-new-console.png) Per modificare una parte della documentazione esistente, procedi come segue: 1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**. 1. È possibile selezionare il metodo o la risorsa contenente il metodo, quindi utilizzare la barra di ricerca per trovare e scegliere la parte della documentazione. 1. Scegli **Modifica**. ## Documentare un'entità `QUERY_PARAMETER` Per aggiungere una nuova parte della documentazione per un'entità `QUERY_PARAMETER`, procedi come segue: 1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**. 1. Per **Tipo di documentazione** seleziona **Parametro di query**. 1. Per **Percorso** inserisci un percorso. 1. Per **Metodo** seleziona un verbo HTTP. 1. In **Nome**, immetti un nome. 1. Immetti una descrizione nell'editor di testo. 1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per un parametro di query non elencato. 1. Se necessario, ripeti queste fasi per aggiungere o modificare un'altra parte della documentazione. Per modificare una parte della documentazione esistente, procedi come segue: 1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**. 1. È possibile selezionare il parametro di query o la risorsa contenente il parametro di query, quindi utilizzare la barra di ricerca per trovare e scegliere la parte della documentazione. 1. Scegli **Modifica**. ## Documentare un'entità `PATH_PARAMETER` Per aggiungere una nuova parte della documentazione per un'entità `PATH_PARAMETER`, procedi come segue: 1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**. 1. Per **Tipo di documentazione** seleziona **Parametro di percorso**. 1. Per **Percorso** inserisci un percorso. 1. Per **Metodo** seleziona un verbo HTTP. 1. In **Nome**, immetti un nome. 1. Immetti una descrizione nell'editor di testo. 1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per un parametro di percorso non elencato. 1. Se necessario, ripeti queste fasi per aggiungere o modificare un'altra parte della documentazione. Per modificare una parte della documentazione esistente, procedi come segue: 1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**. 1. È possibile selezionare il parametro di percorso o la risorsa contenente il parametro di percorso, quindi utilizzare la barra di ricerca per trovare e scegliere la parte della documentazione. 1. Scegli **Modifica**. ## Documentare un'entità `REQUEST_HEADER` Per aggiungere una nuova parte della documentazione per un'entità `REQUEST_HEADER`, procedi come segue: 1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**. 1. Per **Tipo di documentazione** seleziona **Intestazione della richiesta**. 1. Per **Percorso** inserisci il percorso dell'intestazione della richiesta. 1. Per **Metodo** seleziona un verbo HTTP. 1. In **Nome**, immetti un nome. 1. Immetti una descrizione nell'editor di testo. 1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per un'intestazione della richiesta non elencata. 1. Se necessario, ripeti queste fasi per aggiungere o modificare un'altra parte della documentazione. Per modificare una parte della documentazione esistente, procedi come segue: 1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**. 1. È possibile selezionare l'intestazione della richiesta o la risorsa contenente l'intestazione della richiesta, quindi utilizzare la barra di ricerca per trovare e scegliere la parte della documentazione. 1. Scegli **Modifica**. ## Documentare un'entità `REQUEST_BODY` Per aggiungere una nuova parte della documentazione per un'entità `REQUEST_BODY`, procedi come segue: 1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**. 1. Per **Tipo di documentazione** seleziona **Corpo della richiesta**. 1. Per **Percorso** inserisci il percorso del corpo della richiesta. 1. Per **Metodo** seleziona un verbo HTTP. 1. Immetti una descrizione nell'editor di testo. 1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per un corpo della richiesta non elencato. 1. Se necessario, ripeti queste fasi per aggiungere o modificare un'altra parte della documentazione. Per modificare una parte della documentazione esistente, procedi come segue: 1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**. 1. È possibile selezionare il corpo della richiesta o la risorsa contenente il corpo della richiesta, quindi utilizzare la barra di ricerca per trovare e scegliere la parte della documentazione. 1. Scegli **Modifica**. ## Documentare un'entità `RESPONSE` Per aggiungere una nuova parte della documentazione per un'entità `RESPONSE`, procedi come segue: 1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**. 1. Per **Tipo di documentazione** seleziona **Risposta (codice di stato)**. 1. Per **Percorso** inserisci un percorso per la risposta. 1. Per **Metodo** seleziona un verbo HTTP. 1. Per **Codice di stato** inserisci un codice di stato HTTP. 1. Immetti una descrizione nell'editor di testo. 1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per un codice di stato della risposta non elencato. 1. Se necessario, ripeti queste fasi per aggiungere o modificare un'altra parte della documentazione. Per modificare una parte della documentazione esistente, procedi come segue: 1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**. 1. È possibile selezionare il codice di stato della risposta o la risorsa contenente il codice di stato della risposta, quindi utilizzare la barra di ricerca per trovare e scegliere la parte della documentazione. 1. Scegli **Modifica**. ## Documentare un'entità `RESPONSE_HEADER` Per aggiungere una nuova parte della documentazione per un'entità `RESPONSE_HEADER`, procedi come segue: 1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**. 1. Per **Tipo di documentazione** seleziona **Intestazione della risposta**. 1. Per **Percorso** inserisci un percorso per l'intestazione della risposta. 1. Per **Metodo** seleziona un verbo HTTP. 1. Per **Codice di stato** inserisci un codice di stato HTTP. 1. Immetti una descrizione nell'editor di testo. 1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per un'intestazione della risposta non elencata. 1. Se necessario, ripeti queste fasi per aggiungere o modificare un'altra parte della documentazione. Per modificare una parte della documentazione esistente, procedi come segue: 1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**. 1. È possibile selezionare l'intestazione della risposta o la risorsa contenente l'intestazione della risposta, quindi utilizzare la barra di ricerca per trovare e scegliere la parte della documentazione. 1. Scegli **Modifica**. ## Documentare un'entità `RESPONSE_BODY` Per aggiungere una nuova parte della documentazione per un'entità `RESPONSE_BODY`, procedi come segue: 1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**. 1. Per **Tipo di documentazione** seleziona **Corpo della risposta**. 1. Per **Percorso** inserisci un percorso per il corpo della risposta. 1. Per **Metodo** seleziona un verbo HTTP. 1. Per **Codice di stato** inserisci un codice di stato HTTP. 1. Immetti una descrizione nell'editor di testo. 1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per un corpo della risposta non elencato. 1. Se necessario, ripeti queste fasi per aggiungere o modificare un'altra parte della documentazione. Per modificare una parte della documentazione esistente, procedi come segue: 1. Nel riquadro **Documentazione** scegli la scheda **Risorse e metodi**. 1. È possibile selezionare il corpo della risposta o la risorsa contenente il corpo della risposta, quindi utilizzare la barra di ricerca per trovare e scegliere la parte della documentazione. 1. Scegli **Modifica**. ## Documentare un'entità `MODEL` La documentazione di un'entità `MODEL` comporta la creazione e la gestione delle istanze di `DocumentPart` per il modello e gli elementi `properties` del modello. Ad esempio, per il modello `Error` fornito con ogni API per impostazione predefinita ha la seguente definizione dello schema: ``` { "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "Error Schema", "type" : "object", "properties" : { "message" : { "type" : "string" } } } ``` e richiede due istanze di `DocumentationPart`, una per `Model` e l'altra per la relativa proprietà `message`: ``` { "location": { "type": "MODEL", "name": "Error" }, "properties": { "title": "Error Schema", "description": "A description of the Error model" } } ``` e ``` { "location": { "type": "MODEL", "name": "Error.message" }, "properties": { "description": "An error message." } } ``` Quando l'API viene esportata, le proprietà di `DocumentationPart` sostituiscono i valori dello schema originale. Per aggiungere una nuova parte della documentazione per un'entità `MODEL`, procedi come segue: 1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**. 1. Per **Tipo di documentazione** seleziona **Modello**. 1. Per **Nome** inserisci un nome per il processo. 1. Immetti una descrizione nell'editor di testo. 1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per modelli non elencati. 1. Se necessario, ripeti queste fasi per aggiungere o modificare una parte della documentazione per altri modelli. Per aggiungere una nuova parte della documentazione per un'entità `MODEL` nel riquadro **Modelli**, procedi come segue: 1. Nel riquadro di navigazione principale seleziona **Modelli**. 1. Scegli il modello, quindi seleziona **Aggiorna documentazione**. ![\[Modifica della documentazione per l'entità modello nella console Gateway API\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/document-model-entity-using-new-console.png) Per modificare una parte della documentazione esistente, procedi come segue: 1. Nel riquadro **Documentazione** scegli la scheda **Modelli**. 1. Utilizza la barra di ricerca o seleziona il modello, quindi scegli **Modifica**. ## Documentare un'entità `AUTHORIZER` Per aggiungere una nuova parte della documentazione per un'entità `AUTHORIZER`, procedi come segue: 1. Nel riquadro di navigazione principale scegli **Documentazione**, quindi seleziona **Crea parte della documentazione**. 1. Per **Tipo di documentazione** seleziona **Sistema di autorizzazione**. 1. Per **Nome** immetti il nome del sistema di autorizzazione. 1. Immetti una descrizione nell'editor di testo. Specifica un valore per il campo `location` valido per il sistema di autorizzazione. 1. Scegli **Crea parte della documentazione**. È possibile creare la documentazione per sistemi di autorizzazione non elencati. 1. Se necessario, ripeti queste fasi per aggiungere o modificare una parte della documentazione per altre autorizzazioni. Per modificare una parte della documentazione esistente, procedi come segue: 1. Nel riquadro **Documentazione** scegli la scheda **Sistemi di autorizzazione**. 1. Utilizza la barra di ricerca o seleziona il sistema di autorizzazione, quindi scegli **Modifica**. # Pubblicare la documentazione dell'API utilizzando la console API Gateway La procedura seguente mostra come pubblicare una versione della documentazione. **Per pubblicare una versione della documentazione utilizzando la console API Gateway** 1. Nel riquadro di navigazione principale scegli **Documentazione**. 1. Seleziona **Pubblica documentazione**. 1. Configura la pubblicazione: 1. In **Fase**, seleziona una fase. 1. Per **Versione** inserisci un identificatore di versione, ad esempio `1.0.0`. 1. (Facoltativo) In **Descrizione**, immetti una descrizione. 1. Seleziona **Publish** (Pubblica). Ora puoi procedere con il download della documentazione pubblicata esportando la documentazione in un file OpenAPI esterno. Per ulteriori informazioni, consulta [Esportazione di un'API REST da API Gateway](api-gateway-export-api.md). # Documentare un'API utilizzando l'API REST di API Gateway In questa sezione viene descritto come creare e gestire la parti della documentazione di un'API tramite l'API REST di API Gateway. Un prerequisito per la creazione e la modifica della documentazione di un'API è aver già creato l'API. In questa sezione, utilizziamo l'[PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets)API come esempio. Per creare un'API utilizzando la console API Gateway, seguire le istruzioni in [Tutorial: creazione di un'API REST mediante l'importazione di un esempio](api-gateway-create-api-from-example.md). **Topics** + [Documentare l'entità `API`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-api) + [Documentare un'entità `RESOURCE`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-resource) + [Documentare un'entità `METHOD`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-method) + [Documentare un'entità `QUERY_PARAMETER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-query-parameter) + [Documentare un'entità `PATH_PARAMETER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-path-parameter) + [Documentare un'entità `REQUEST_BODY`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-body) + [Documentare un'entità `REQUEST_HEADER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-header) + [Documentare un'entità `RESPONSE`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response) + [Documentare un'entità `RESPONSE_HEADER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response-header) + [Documentare un'entità `AUTHORIZER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-authorizer) + [Documentare un'entità `MODEL`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-model) + [Aggiornare le parti della documentazione](#api-gateway-documenting-api-quick-start-with-restapi-update-content) + [Elencare le parti della documentazione](#api-gateway-documenting-api-quick-start-with-restapi-list-parts) ## Documentare l'entità `API` Per aggiungere la documentazione per un'[API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa per l'entità API: ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "API" }, "properties": "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}" } ``` Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio: ``` { ... "id": "s2e5xf", "location": { "path": null, "method": null, "name": null, "statusCode": null, "type": "API" }, "properties": "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}" } ``` Se la documentazione è già stata aggiunta, viene restituita una risposta `409 Conflict` contenente il messaggio di errore `Documentation part already exists for the specified location: type 'API'."`. In questo caso è necessario eseguire l'operazione [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html). ``` PATCH /restapis/4wk1k4onj3/documentation/parts/part_id HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "patchOperations" : [ { "op" : "replace", "path" : "/properties", "value" : "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}" } ] } ``` La risposta con esito positivo restituisce un codice di stato `200 OK` con un payload che include l'istanza `DocumentationPart` aggiornata nel payload. ## Documentare un'entità `RESOURCE` Per aggiungere la documentazione per la risorsa principale di un'API, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa destinata alla risorsa di [risorsa](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) corrispondente: ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "RESOURCE", }, "properties" : "{\n\t\"description\" : \"The PetStore root resource.\"\n}" } ``` Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo" } }, "id": "p76vqo", "location": { "path": "/", "method": null, "name": null, "statusCode": null, "type": "RESOURCE" }, "properties": "{\n\t\"description\" : \"The PetStore root resource.\"\n}" } ``` Quando il percorso della risorsa non è specificato, si presume che la risorsa sia la risorsa radice. Puoi aggiungere `"path": "/"` a `properties` per rendere esplicita la specifica. Per creare la documentazione per una risorsa figlia di un'API, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa destinata alla risorsa [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) corrispondente: ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "RESOURCE", "path" : "/pets" }, "properties": "{\n\t\"description\" : \"A child resource under the root of PetStore.\"\n}" } ``` Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Esempio: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/qcht86" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/qcht86" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/qcht86" } }, "id": "qcht86", "location": { "path": "/pets", "method": null, "name": null, "statusCode": null, "type": "RESOURCE" }, "properties": "{\n\t\"description\" : \"A child resource under the root of PetStore.\"\n}" } ``` Per aggiungere la documentazione per una risorsa secondaria specificata da un parametro path, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa destinata alla [risorsa Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html): ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "RESOURCE", "path" : "/pets/{petId}" }, "properties": "{\n\t\"description\" : \"A child resource specified by the petId path parameter.\"\n}" } ``` Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Esempio: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb" } }, "id": "k6fpwb", "location": { "path": "/pets/{petId}", "method": null, "name": null, "statusCode": null, "type": "RESOURCE" }, "properties": "{\n\t\"description\" : \"A child resource specified by the petId path parameter.\"\n}" } ``` **Nota** L'[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)istanza di un'`RESOURCE`entità non può essere ereditata da nessuna delle sue risorse secondarie. ## Documentare un'entità `METHOD` Per aggiungere la documentazione per un metodo di un'API, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa destinata alla risorsa [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) corrispondente: ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "METHOD", "path" : "/pets", "method" : "GET" }, "properties": "{\n\t\"summary\" : \"List all pets.\"\n}" } ``` Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" } }, "id": "o64jbj", "location": { "path": "/pets", "method": "GET", "name": null, "statusCode": null, "type": "METHOD" }, "properties": "{\n\t\"summary\" : \"List all pets.\"\n}" } ``` Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" } }, "id": "o64jbj", "location": { "path": "/pets", "method": "GET", "name": null, "statusCode": null, "type": "METHOD" }, "properties": "{\n\t\"summary\" : \"List all pets.\"\n}" } ``` Se il campo `location.method` non è specificato nella richiesta precedente, si presume che sia il metodo `ANY` rappresentato da un carattere jolly `*`. Per aggiornare il contenuto della documentazione di un'entità `METHOD`, chiamare l'operazione [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html), fornendo una nuova mappa di `properties`: ``` PATCH /restapis/4wk1k4onj3/documentation/parts/part_id HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "patchOperations" : [ { "op" : "replace", "path" : "/properties", "value" : "{\n\t\"tags\" : [ \"pets\" ], \n\t\"summary\" : \"List all pets.\"\n}" } ] } ``` La risposta con esito positivo restituisce un codice di stato `200 OK` con un payload che include l'istanza `DocumentationPart` aggiornata nel payload. Ad esempio: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" } }, "id": "o64jbj", "location": { "path": "/pets", "method": "GET", "name": null, "statusCode": null, "type": "METHOD" }, "properties": "{\n\t\"tags\" : [ \"pets\" ], \n\t\"summary\" : \"List all pets.\"\n}" } ``` ## Documentare un'entità `QUERY_PARAMETER` Per aggiungere la documentazione per un parametro di query di richiesta, aggiungete una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa mirata al `QUERY_PARAMETER` tipo, con i campi validi di `path` and`name`. ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "QUERY_PARAMETER", "path" : "/pets", "method" : "GET", "name" : "page" }, "properties": "{\n\t\"description\" : \"Page number of results to return.\"\n}" } ``` Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w" } }, "id": "h9ht5w", "location": { "path": "/pets", "method": "GET", "name": "page", "statusCode": null, "type": "QUERY_PARAMETER" }, "properties": "{\n\t\"description\" : \"Page number of results to return.\"\n}" } ``` La mappa di `properties` della parte della documentazione di un'entità `QUERY_PARAMETER` può essere ereditata da uno delle relative entità figlio `QUERY_PARAMETER`. Ad esempio se aggiungi una risorsa `treats` dopo `/pets/{petId}`, abiliti il metodo `GET` su `/pets/{petId}/treats` ed esponi il parametro di query `page`, questo parametro di query figlio eredita la mappa di `DocumentationPart` di `properties` dal parametro di query con nome simile del metodo `GET /pets`, a meno che non aggiungi esplicitamente una risorsa `DocumentationPart` al parametro di query `page` del metodo `GET /pets/{petId}/treats`. ## Documentare un'entità `PATH_PARAMETER` Per aggiungere la documentazione per un parametro di percorso, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa per l'`PATH_PARAMETER`entità. ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "PATH_PARAMETER", "path" : "/pets/{petId}", "method" : "*", "name" : "petId" }, "properties": "{\n\t\"description\" : \"The id of the pet to retrieve.\"\n}" } ``` Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog" } }, "id": "ckpgog", "location": { "path": "/pets/{petId}", "method": "*", "name": "petId", "statusCode": null, "type": "PATH_PARAMETER" }, "properties": "{\n \"description\" : \"The id of the pet to retrieve\"\n}" } ``` ## Documentare un'entità `REQUEST_BODY` Per aggiungere documentazione per un corpo della richiesta, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa per il corpo della richiesta. ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "REQUEST_BODY", "path" : "/pets", "method" : "POST" }, "properties": "{\n\t\"description\" : \"A Pet object to be added to PetStore.\"\n}" } ``` Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1" } }, "id": "kgmfr1", "location": { "path": "/pets", "method": "POST", "name": null, "statusCode": null, "type": "REQUEST_BODY" }, "properties": "{\n\t\"description\" : \"A Pet object to be added to PetStore.\"\n}" } ``` ## Documentare un'entità `REQUEST_HEADER` Per aggiungere documentazione per l'intestazione di una richiesta, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa per l'intestazione della richiesta. ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "REQUEST_HEADER", "path" : "/pets", "method" : "GET", "name" : "x-my-token" }, "properties": "{\n\t\"description\" : \"A custom token used to authorization the method invocation.\"\n}" } ``` Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf" } }, "id": "h0m3uf", "location": { "path": "/pets", "method": "GET", "name": "x-my-token", "statusCode": null, "type": "REQUEST_HEADER" }, "properties": "{\n\t\"description\" : \"A custom token used to authorization the method invocation.\"\n}" } ``` ## Documentare un'entità `RESPONSE` Per aggiungere la documentazione per una risposta a un codice di stato, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa destinata alla risorsa corrispondente [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html). ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location": { "path": "/", "method": "*", "name": null, "statusCode": "200", "type": "RESPONSE" }, "properties": "{\n \"description\" : \"Successful operation.\"\n}" } ``` Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio: ``` { "_links": { "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/lattew" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/lattew" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/lattew" } }, "id": "lattew", "location": { "path": "/", "method": "*", "name": null, "statusCode": "200", "type": "RESPONSE" }, "properties": "{\n \"description\" : \"Successful operation.\"\n}" } ``` ## Documentare un'entità `RESPONSE_HEADER` Per aggiungere la documentazione per un'intestazione di risposta, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa per l'intestazione della risposta. ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret "location": { "path": "/", "method": "GET", "name": "Content-Type", "statusCode": "200", "type": "RESPONSE_HEADER" }, "properties": "{\n \"description\" : \"Media type of request\"\n}" ``` Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Ad esempio: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7" } }, "id": "fev7j7", "location": { "path": "/", "method": "GET", "name": "Content-Type", "statusCode": "200", "type": "RESPONSE_HEADER" }, "properties": "{\n \"description\" : \"Media type of request\"\n}" } ``` La documentazione di questa intestazione di risposta `Content-Type` è la documentazione predefinita per le intestazioni `Content-Type` di qualsiasi risposta dell'API. ## Documentare un'entità `AUTHORIZER` Per aggiungere documentazione per un autorizzatore API, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa destinata all'autorizzatore specificato. ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "AUTHORIZER", "name" : "myAuthorizer" }, "properties": "{\n\t\"description\" : \"Authorizes invocations of configured methods.\"\n}" } ``` Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Esempio: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3" } }, "id": "pw3qw3", "location": { "path": null, "method": null, "name": "myAuthorizer", "statusCode": null, "type": "AUTHORIZER" }, "properties": "{\n\t\"description\" : \"Authorizes invocations of configured methods.\"\n}" } ``` **Nota** L'[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)istanza di un'`AUTHORIZER`entità non può essere ereditata da nessuna delle sue risorse secondarie. ## Documentare un'entità `MODEL` La documentazione di un'entità `MODEL` comporta la creazione e la gestione delle istanze di `DocumentPart` per il modello e gli elementi `properties` del modello. Ad esempio, per il modello `Error` fornito con ogni API per impostazione predefinita ha la seguente definizione dello schema: ``` { "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "Error Schema", "type" : "object", "properties" : { "message" : { "type" : "string" } } } ``` e richiede due istanze di `DocumentationPart`, una per `Model` e l'altra per la relativa proprietà `message`: ``` { "location": { "type": "MODEL", "name": "Error" }, "properties": { "title": "Error Schema", "description": "A description of the Error model" } } ``` e ``` { "location": { "type": "MODEL", "name": "Error.message" }, "properties": { "description": "An error message." } } ``` Quando l'API viene esportata, le proprietà di `DocumentationPart` sostituiscono i valori dello schema originale. Per aggiungere documentazione per un modello API, aggiungi una [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)risorsa destinata al modello specificato. ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "MODEL", "name" : "Pet" }, "properties": "{\n\t\"description\" : \"Data structure of a Pet object.\"\n}" } ``` Se con esito positivo, l'operazione restituisce una risposta `201 Created` contenente la nuova istanza `DocumentationPart` creata nel payload. Esempio: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq" } }, "id": "lkn4uq", "location": { "path": null, "method": null, "name": "Pet", "statusCode": null, "type": "MODEL" }, "properties": "{\n\t\"description\" : \"Data structure of a Pet object.\"\n}" } ``` Ripetete lo stesso passaggio per creare un' DocumentationPart istanza per una qualsiasi delle proprietà del modello. **Nota** L'[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)istanza di un'`MODEL`entità non può essere ereditata da nessuna delle sue risorse secondarie. ## Aggiornare le parti della documentazione Per aggiornare le parti della documentazione di qualsiasi tipo di entità API, invia una richiesta PATCH su un'[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)istanza di un identificatore di parte specificato per sostituire la `properties` mappa esistente con una nuova. ``` PATCH /restapis/4wk1k4onj3/documentation/parts/part_id HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "patchOperations" : [ { "op" : "replace", "path" : "RESOURCE_PATH", "value" : "NEW_properties_VALUE_AS_JSON_STRING" } ] } ``` La risposta con esito positivo restituisce un codice di stato `200 OK` con un payload che include l'istanza `DocumentationPart` aggiornata nel payload. Puoi aggiornare più parti della documentazione in una singola richiesta `PATCH`. ## Elencare le parti della documentazione Per elencare le parti della documentazione di qualsiasi tipo di entità API, invia una richiesta GET su una [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)raccolta. ``` GET /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret ``` La risposta con esito positivo restituisce un codice di stato `200 OK` con un payload che include le istanze `DocumentationPart` disponibili nel payload. # Pubblicare la documentazione dell'API utilizzando l'API REST di API Gateway Per pubblicare la documentazione per un'API, crea, aggiorna o ottieni uno snapshot della documentazione, quindi associa lo snapshot della documentazione a una fase dell'API. Quando crei uno snapshot della documentazione, puoi anche contemporaneamente associarlo a una fase dell'API. **Topics** + [Creare uno snapshot della documentazione e associarlo a una fase dell'API](#api-gateway-documenting-api-publishing-create-documentation-version-with-stage) + [Creare uno snapshot della documentazione](#api-gateway-documenting-api-publishing-create-documentation-version) + [Aggiornare uno snapshot della documentazione](#api-gateway-documenting-api-publishing-update-documentation-version) + [Ottenere uno snapshot della documentazione](#api-gateway-documenting-api-publishing-get-documentation-version) + [Associare uno snapshot della documentazione a una fase dell'API](#api-gateway-documenting-api-publishing-stage-association) + [Scaricare uno snapshot della documentazione associato a una fase](#api-gateway-documenting-api-publishing-export-documentation-version) ## Creare uno snapshot della documentazione e associarlo a una fase dell'API Per creare uno snapshot delle parti della documentazione di un'API e associarlo contemporaneamente a una fase dell'API, invia la seguente richiesta `POST`: ``` POST /restapis/restapi_id/documentation/versions HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "documentationVersion" : "1.0.0", "stageName": "prod", "description" : "My API Documentation v1.0.0" } ``` Se con esito positivo, l'operazione restituisce una risposta `200 OK` contenente la nuova istanza `DocumentationVersion` creata come payload. In alternativa, è possibile creare uno snapshot della documentazione senza associarlo prima a una fase dell'API e quindi chiamare [restapi:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) per associare lo snapshot a una fase dell'API specificata. Puoi inoltre aggiornare o interrogare uno snapshot della documentazione esistente e quindi aggiornare la relativa associazione della fase. Le fasi vengono illustrate nelle prossime quattro sezioni. ## Creare uno snapshot della documentazione Per creare un'istantanea delle parti della documentazione di un'API, crea una nuova [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)risorsa e aggiungila alla [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)raccolta dell'API: ``` POST /restapis/restapi_id/documentation/versions HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "documentationVersion" : "1.0.0", "description" : "My API Documentation v1.0.0" } ``` Se con esito positivo, l'operazione restituisce una risposta `200 OK` contenente la nuova istanza `DocumentationVersion` creata come payload. ## Aggiornare uno snapshot della documentazione È possibile aggiornare un'istantanea della documentazione solo modificando la `description` proprietà della risorsa corrispondente. [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) L'esempio seguente mostra come aggiornare la descrizione dello snapshot della documentazione come identificata dal relativo identificatore di versione, `version`, ad esempio `1.0.0`. ``` PATCH /restapis/restapi_id/documentation/versions/version HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "patchOperations": [{ "op": "replace", "path": "/description", "value": "My API for testing purposes." }] } ``` Se con esito positivo, l'operazione restituisce una risposta `200 OK` contenente l'istanza `DocumentationVersion` aggiornata come payload. ## Ottenere uno snapshot della documentazione Per ottenere un'istantanea della documentazione, invia una `GET` richiesta relativa alla risorsa specificata. [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) L'esempio seguente mostra come ottenere uno snapshot della documentazione di un dato identificatore di versione, 1.0.0. ``` GET /restapis//documentation/versions/1.0.0 HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret ``` ## Associare uno snapshot della documentazione a una fase dell'API Per pubblicare la documentazione dell'API, associa uno snapshot della documentazione a una fase dell'API. Devi aver già creato la fase dell'API prima di associare la versione della documentazione alla fase. Per associare uno snapshot della documentazione a una fase dell'API utilizzando l'[API REST di API Gateway](https://docs.aws.amazon.com/apigateway/latest/api/), esegui l'operazione [stage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) per impostare a versione della documentazione desiderata sulla proprietà `stage.documentationVersion`: ``` PATCH /restapis/RESTAPI_ID/stages/STAGE_NAME Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "patchOperations": [{ "op": "replace", "path": "/documentationVersion", "value": "VERSION_IDENTIFIER" }] } ``` ## Scaricare uno snapshot della documentazione associato a una fase Dopo aver associato una versione delle parti della documentazione a uno stage, è possibile esportare le parti della documentazione insieme alle definizioni delle entità API, in un file esterno, utilizzando la console API Gateway, l'API REST API Gateway, una delle sue SDKs, o il AWS CLI for API Gateway. Il processo è uguale a quello utilizzato per esportare l'API. Il formato del file esportato può essere JSON o YAML. Utilizzando l'API REST di API Gateway, puoi anche impostare esplicitamente il parametro di query `extension=documentation,integrations,authorizers` per includere le parti della documentazione dell'API, le integrazioni API e le autorizzazioni in un'esportazione API. Per impostazione predefinita, le parti della documentazione sono incluse, ma le integrazioni e le autorizzazioni sono escluse quando si esporta un'API. L'output predefinito di un'esportazione API è adatto per la distribuzione della documentazione. Per esportare la documentazione dell'API in un file OpenAPI JSON esterno usando l'API REST di API Gateway, inviare la seguente richiesta `GET`: ``` GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=documentation HTTP/1.1 Accept: application/json Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret ``` Qui, l'oggetto `x-amazon-apigateway-documentation` contiene le parti della documentazione e la definizione dell'entità API contiene le proprietà della documentazione supportate da OpenAPI. L'output non include dettagli sull'integrazione o sulle autorizzazioni Lambda (note in precedenza come autorizzazioni ad hoc). Per includere entrambi i dettagli, imposta `extensions=integrations,authorizers,documentation`. Per includere i dettagli delle integrazioni ma non delle autorizzazioni, imposta `extensions=integrations,documentation`. Imposta l'intestazione `Accept:application/json` nella richiesta per inserire l'output del risultato in un file JSON. Per produrre l'output YAML, imposta l'intestazione della richiesta su `Accept:application/yaml`. Ad esempio, esamineremo un'API che espone un semplice metodo `GET` sulla risorsa radice (`/`). Questa API ha quattro entità API definite in un file di definizione OpenAPI, uno per ciascuno dei tipi `API`, `MODEL`, `METHOD` e `RESPONSE`. Una parte della documentazione è stata aggiunta a ciascuna delle entità `API`, `METHOD` e `RESPONSE`. Chiamando il precedente comando di esportazione della documentazione, otteniamo il seguente output, con le parti della documentazione elencate nell'oggetto `x-amazon-apigateway-documentation` come estensione di un file OpenAPI standard. ------ #### [ OpenAPI 3.0 ] ``` { "openapi": "3.0.0", "info": { "description": "API info description", "version": "2016-11-22T22:39:14Z", "title": "doc", "x-bar": "API info x-bar" }, "paths": { "/": { "get": { "description": "Method description.", "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } } }, "x-example": "x- Method example" }, "x-bar": "resource x-bar" } }, "x-amazon-apigateway-documentation": { "version": "1.0.0", "createdDate": "2016-11-22T22:41:40Z", "documentationParts": [ { "location": { "type": "API" }, "properties": { "description": "API description", "foo": "API foo", "x-bar": "API x-bar", "info": { "description": "API info description", "version": "API info version", "foo": "API info foo", "x-bar": "API info x-bar" } } }, { "location": { "type": "METHOD", "method": "GET" }, "properties": { "description": "Method description.", "x-example": "x- Method example", "foo": "Method foo", "info": { "version": "method info version", "description": "method info description", "foo": "method info foo" } } }, { "location": { "type": "RESOURCE" }, "properties": { "description": "resource description", "foo": "resource foo", "x-bar": "resource x-bar", "info": { "description": "resource info description", "version": "resource info version", "foo": "resource info foo", "x-bar": "resource info x-bar" } } } ] }, "x-bar": "API x-bar", "servers": [ { "url": "https://rznaap68yi.execute-api.ap-southeast-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/test" } } } ], "components": { "schemas": { "Empty": { "type": "object", "title": "Empty Schema" } } } } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger" : "2.0", "info" : { "description" : "API info description", "version" : "2016-11-22T22:39:14Z", "title" : "doc", "x-bar" : "API info x-bar" }, "host" : "rznaap68yi.execute-api.ap-southeast-1.amazonaws.com", "basePath" : "/test", "schemes" : [ "https" ], "paths" : { "/" : { "get" : { "description" : "Method description.", "produces" : [ "application/json" ], "responses" : { "200" : { "description" : "200 response", "schema" : { "$ref" : "#/definitions/Empty" } } }, "x-example" : "x- Method example" }, "x-bar" : "resource x-bar" } }, "definitions" : { "Empty" : { "type" : "object", "title" : "Empty Schema" } }, "x-amazon-apigateway-documentation" : { "version" : "1.0.0", "createdDate" : "2016-11-22T22:41:40Z", "documentationParts" : [ { "location" : { "type" : "API" }, "properties" : { "description" : "API description", "foo" : "API foo", "x-bar" : "API x-bar", "info" : { "description" : "API info description", "version" : "API info version", "foo" : "API info foo", "x-bar" : "API info x-bar" } } }, { "location" : { "type" : "METHOD", "method" : "GET" }, "properties" : { "description" : "Method description.", "x-example" : "x- Method example", "foo" : "Method foo", "info" : { "version" : "method info version", "description" : "method info description", "foo" : "method info foo" } } }, { "location" : { "type" : "RESOURCE" }, "properties" : { "description" : "resource description", "foo" : "resource foo", "x-bar" : "resource x-bar", "info" : { "description" : "resource info description", "version" : "resource info version", "foo" : "resource info foo", "x-bar" : "resource info x-bar" } } } ] }, "x-bar" : "API x-bar" } ``` ------ Per un attributo conforme a OpenAPI definito nella mappa di `properties` di una parte della documentazione, API Gateway inserisce l'attributo nella definizione dell'entità API associata. Un attributo di `x-something` è un'estensione OpenAPI standard. Questa estensione viene propagata nella definizione dell'entità API. Ad esempio, consulta l'attributo `x-example` per il metodo `GET`. Un attributo come `foo` non fa parte delle specifiche OpenAPI e non viene inserito nelle definizioni delle entità API associate. Se uno strumento di rendering della documentazione (ad esempio [OpenAPI UI](https://swagger.io/tools/swagger-ui/)) analizza le definizioni dell'entità API per estrarre gli attributi della documentazione, qualsiasi attributo `properties` non conforme a OpenAPI di un'istanza di `DocumentationPart` non è disponibile per lo strumento. Tuttavia, se uno strumento di rendering della documentazione analizza l'oggetto `x-amazon-apigateway-documentation` per ottenere i contenuti o se lo strumento chiama [restapi:documentation-parts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) e [documenationpart:by-id](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationPart.html) per recuperare le parti della documentazione da API Gateway, tutti gli attributi della documentazione sono disponibili per la visualizzazione con lo strumento. Per esportare la documentazione con definizioni di entità API contenenti i dettagli delle integrazioni in un file OpenAPI JSON, inviare la seguente richiesta `GET`: ``` GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,documentation HTTP/1.1 Accept: application/json Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret ``` Per esportare la documentazione con definizioni di entità API contenenti dettagli delle integrazioni e delle autorizzazioni in un file OpenAPI YAML, inviare la seguente richiesta `GET`: ``` GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,authorizers,documentation HTTP/1.1 Accept: application/yaml Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret ``` Per usare la console API Gateway per esportare e scaricare la documentazione pubblicata di un'API, segui le istruzioni in [Esportazione di un'API REST tramite la console API Gateway](api-gateway-export-api.md#api-gateway-export-api-from-console). # Importare la documentazione dell'API Come con l'importazione delle definizioni di entità API, puoi importare le parti della documentazione da un file OpenAPI esterno in un'API di API Gateway. Specificate le parti della to-be-imported documentazione all'interno dell'[x-amazon-apigateway-documentation oggetto](api-gateway-swagger-extensions-documentation.md)estensione in un file di definizione OpenAPI valido. L'importazione della documentazione non modifica le definizioni delle entità API esistenti. Esiste la possibilità di unire le parti della documentazione appena specificate in parti della documentazione esistenti in API Gateway o per sovrascrivere le parti della documentazione esistenti. Nella modalità `MERGE`, una nuova parte della documentazione definita nel file OpenAPI viene aggiunta alla raccolta `DocumentationParts` dell'API. Se un elemento `DocumentationPart` importato esiste già, un attributo importato sostituisce quello esistente se i due sono diversi. Altri attributi della documentazione esistenti rimangono inalterati. Nella modalità `OVERWRITE`, l'intera raccolta `DocumentationParts` viene sostituita in base al file di definizione OpenAPI importato. ## Importazione delle parti della documentazione tramite l'API REST di API Gateway Per importare la documentazione dell'API usando l'API REST di API Gateway, esegui l'operazione [documentationpart:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportDocumentationParts.html). L'esempio seguente mostra come sovrascrivere parti della documentazione esistenti di un'API con un singolo metodo `GET / `, restituendo una risposta `200 OK` per l'esito positivo. ------ #### [ OpenAPI 3.0 ] ``` PUT /restapis//documentation/parts&mode=overwrite&failonwarnings=true Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "openapi": "3.0.0", "info": { "description": "description", "version": "1", "title": "doc" }, "paths": { "/": { "get": { "description": "Method description.", "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } } } } } }, "x-amazon-apigateway-documentation": { "version": "1.0.3", "documentationParts": [ { "location": { "type": "API" }, "properties": { "description": "API description", "info": { "description": "API info description 4", "version": "API info version 3" } } }, { "location": { "type": "METHOD", "method": "GET" }, "properties": { "description": "Method description." } }, { "location": { "type": "MODEL", "name": "Empty" }, "properties": { "title": "Empty Schema" } }, { "location": { "type": "RESPONSE", "method": "GET", "statusCode": "200" }, "properties": { "description": "200 response" } } ] }, "servers": [ { "url": "/" } ], "components": { "schemas": { "Empty": { "type": "object", "title": "Empty Schema" } } } } ``` ------ #### [ OpenAPI 2.0 ] ``` PUT /restapis//documentation/parts&mode=overwrite&failonwarnings=true Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "swagger": "2.0", "info": { "description": "description", "version": "1", "title": "doc" }, "host": "", "basePath": "/", "schemes": [ "https" ], "paths": { "/": { "get": { "description": "Method description.", "produces": [ "application/json" ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } } } } } }, "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } }, "x-amazon-apigateway-documentation": { "version": "1.0.3", "documentationParts": [ { "location": { "type": "API" }, "properties": { "description": "API description", "info": { "description": "API info description 4", "version": "API info version 3" } } }, { "location": { "type": "METHOD", "method": "GET" }, "properties": { "description": "Method description." } }, { "location": { "type": "MODEL", "name": "Empty" }, "properties": { "title": "Empty Schema" } }, { "location": { "type": "RESPONSE", "method": "GET", "statusCode": "200" }, "properties": { "description": "200 response" } } ] } } ``` ------ In caso di esito positivo, questa richiesta restituisce una risposta 200 OK contenente l'elemento `DocumentationPartId` importato nel payload. ``` { "ids": [ "kg3mth", "796rtf", "zhek4p", "5ukm9s" ] } ``` Inoltre, è possibile anche invocare [restapi:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportRestApi.html) o [restapi:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutRestApi.html), fornendo le parti della documentazione nell'oggetto `x-amazon-apigateway-documentation` come parte del file OpenAPI di input della definizione dell'API. Per escludere le parti della documentazione dall'importazione dell'API, imposta `ignore=documentation` nei parametri di query della richiesta. ## Importazione di parti di documentazione tramite la console API Gateway Le seguenti istruzioni descrivono come importare le parti della documentazione. **Per utilizzare la console per importare le parti della documentazione di un'API da un file esterno** 1. Nel riquadro di navigazione principale scegli **Documentazione**. 1. Scegli **Importa**. 1. Se è disponibile la documentazione esistente, seleziona **Sovrascrivi** o **Unisci** per la nuova documentazione. 1. Seleziona **Scegli il file** per caricare un file da un'unità oppure immettere il contenuto di un file nella vista del file. Per un esempio, consulta il payload della richiesta di esempio in [Importazione delle parti della documentazione tramite l'API REST di API Gateway](#api-gateway-importing-api-with-swagger-file-using-rest-api). 1. Scegli in che modo gestire gli avvisi durante l'importazione. Seleziona **Avvisi di errore** o **Ignora avvisi**. Per ulteriori informazioni, consulta [Errori e avvisi relativi all'importazione dell'API in Gateway API](api-gateway-import-api-errors-warnings.md). 1. Scegli **Importa**. # Controllo dell'accesso alla documentazione dell'API in Gateway API Se hai un team dedicato alla documentazione per scrivere e modificare la documentazione dell'API, puoi configurare autorizzazioni di accesso separate per i tuoi sviluppatori (per lo sviluppo dell'API) e per i tuoi scrittori o editori (per lo sviluppo del contenuto). Questo è particolarmente appropriato quando un fornitore di terze parti è coinvolto nella creazione della documentazione. Per concedere al tuo team di documentazione l'accesso per creare, aggiornare e pubblicare la documentazione dell'API, puoi assegnare al team di documentazione un ruolo IAM con la seguente politica IAM, dove si *account\$1id* trova l'ID AWS account del tuo team di documentazione. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "StmtDocPartsAddEditViewDelete", "Effect": "Allow", "Action": [ "apigateway:GET", "apigateway:PUT", "apigateway:POST", "apigateway:PATCH", "apigateway:DELETE" ], "Resource": [ "arn:aws:apigateway:us-east-1:111111111111:/restapis/*/documentation/*" ] } ] } ``` ------ Per informazioni sull'impostazione delle autorizzazioni per accedere alle risorse di API Gateway, consultare [Come funziona Amazon API Gateway con IAM](security_iam_service-with-iam.md).