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à.
# 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**.