Documentare un'API utilizzando la console API Gateway - Amazon API Gateway
Documentare l'entità APIDocumentare un'entità RESOURCEDocumentare un'entità METHODDocumentare un'entità QUERY_PARAMETERDocumentare un'entità PATH_PARAMETER Documentare un'entità REQUEST_HEADERDocumentare un'entità REQUEST_BODYDocumentare un'entità RESPONSEDocumentare un'entità RESPONSE_HEADERDocumentare un'entità RESPONSE_BODYDocumentare un'entità MODELDocumentare un'entità AUTHORIZER

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, usiamo ad esempio l'API PetStore. 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.

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.

  2. 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.

  3. 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.

  2. Scegli il menu Operazioni API, quindi seleziona Aggiorna documentazione dell'API.

    Modificare la documentazione per l'entità API nella console API Gateway

Per modificare una parte della documentazione esistente, procedi come segue:

  1. Nel riquadro Documentazione scegli la scheda Risorse e metodi.

  2. 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.

  2. Per Tipo di documentazione seleziona Risorsa.

  3. Per Percorso inserisci un percorso.

  4. Immetti una descrizione nell'editor di testo, ad esempio:

    {
    "description": "The PetStore's root resource."
}

  5. Scegli Crea parte della documentazione. È possibile creare la documentazione per una risorsa non elencata.

  6. 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.

  2. Scegli la risorsa, quindi seleziona Aggiorna documentazione.

    Modifica della documentazione per l'entità risorsa nella console Gateway API

Per modificare una parte della documentazione esistente, procedi come segue:

  1. Nel riquadro Documentazione scegli la scheda Risorse e metodi.

  2. 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.

  2. Per Tipo di documentazione seleziona Metodo.

  3. Per Percorso inserisci un percorso.

  4. Per Metodo seleziona un verbo HTTP.

  5. Immetti una descrizione nell'editor di testo, ad esempio:

    {
  "tags" : [ "pets" ],
  "summary" : "List all pets"
}

  6. Scegli Crea parte della documentazione. È possibile creare la documentazione per un metodo non elencato.

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

  2. Scegli il metodo, quindi seleziona Aggiorna documentazione.

    Modifica della documentazione per l'entità metodo nella console Gateway API

Per modificare una parte della documentazione esistente, procedi come segue:

  1. Nel riquadro Documentazione scegli la scheda Risorse e metodi.

  2. È possibile selezionare il metodo o la risorsa contenente il metodo, quindi utilizzare la barra di ricerca per trovare e scegliere la parte della documentazione.

  3. 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.

  2. Per Tipo di documentazione seleziona Parametro di query.

  3. Per Percorso inserisci un percorso.

  4. Per Metodo seleziona un verbo HTTP.

  5. In Nome, immetti un nome.

  6. Immetti una descrizione nell'editor di testo.

  7. Scegli Crea parte della documentazione. È possibile creare la documentazione per un parametro di query non elencato.

  8. 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.

  2. È 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.

  3. 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.

  2. Per Tipo di documentazione seleziona Parametro di percorso.

  3. Per Percorso inserisci un percorso.

  4. Per Metodo seleziona un verbo HTTP.

  5. In Nome, immetti un nome.

  6. Immetti una descrizione nell'editor di testo.

  7. Scegli Crea parte della documentazione. È possibile creare la documentazione per un parametro di percorso non elencato.

  8. 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.

  2. È 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.

  3. 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.

  2. Per Tipo di documentazione seleziona Intestazione della richiesta.

  3. Per Percorso inserisci il percorso dell'intestazione della richiesta.

  4. Per Metodo seleziona un verbo HTTP.

  5. In Nome, immetti un nome.

  6. Immetti una descrizione nell'editor di testo.

  7. Scegli Crea parte della documentazione. È possibile creare la documentazione per un'intestazione della richiesta non elencata.

  8. 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.

  2. È 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.

  3. 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.

  2. Per Tipo di documentazione seleziona Corpo della richiesta.

  3. Per Percorso inserisci il percorso del corpo della richiesta.

  4. Per Metodo seleziona un verbo HTTP.

  5. Immetti una descrizione nell'editor di testo.

  6. Scegli Crea parte della documentazione. È possibile creare la documentazione per un corpo della richiesta non elencato.

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

  2. È 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.

  3. 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.

  2. Per Tipo di documentazione seleziona Risposta (codice di stato).

  3. Per Percorso inserisci un percorso per la risposta.

  4. Per Metodo seleziona un verbo HTTP.

  5. Per Codice di stato inserisci un codice di stato HTTP.

  6. Immetti una descrizione nell'editor di testo.

  7. Scegli Crea parte della documentazione. È possibile creare la documentazione per un codice di stato della risposta non elencato.

  8. 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.

  2. È 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.

  3. 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.

  2. Per Tipo di documentazione seleziona Intestazione della risposta.

  3. Per Percorso inserisci un percorso per l'intestazione della risposta.

  4. Per Metodo seleziona un verbo HTTP.

  5. Per Codice di stato inserisci un codice di stato HTTP.

  6. Immetti una descrizione nell'editor di testo.

  7. Scegli Crea parte della documentazione. È possibile creare la documentazione per un'intestazione della risposta non elencata.

  8. 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.

  2. È 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.

  3. 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.

  2. Per Tipo di documentazione seleziona Corpo della risposta.

  3. Per Percorso inserisci un percorso per il corpo della risposta.

  4. Per Metodo seleziona un verbo HTTP.

  5. Per Codice di stato inserisci un codice di stato HTTP.

  6. Immetti una descrizione nell'editor di testo.

  7. Scegli Crea parte della documentazione. È possibile creare la documentazione per un corpo della risposta non elencato.

  8. 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.

  2. È 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.

  3. 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.

  2. Per Tipo di documentazione seleziona Modello.

  3. Per Nome inserisci un nome per il processo.

  4. Immetti una descrizione nell'editor di testo.

  5. Scegli Crea parte della documentazione. È possibile creare la documentazione per modelli non elencati.

  6. 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.

  2. Scegli il modello, quindi seleziona Aggiorna documentazione.

    Modifica della documentazione per l'entità modello nella console Gateway API

Per modificare una parte della documentazione esistente, procedi come segue:

  1. Nel riquadro Documentazione scegli la scheda Modelli.

  2. 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.

  2. Per Tipo di documentazione seleziona Sistema di autorizzazione.

  3. Per Nome immetti il nome del sistema di autorizzazione.

  4. Immetti una descrizione nell'editor di testo. Specifica un valore per il campo location valido per il sistema di autorizzazione.

  5. Scegli Crea parte della documentazione. È possibile creare la documentazione per sistemi di autorizzazione non elencati.

  6. 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.

  2. Utilizza la barra di ricerca o seleziona il sistema di autorizzazione, quindi scegli Modifica.