Documenta e API utilizza la console API Gateway

In questa sezione, descriviamo come creare e gestire parti della documentazione relative all'APIutilizzo della console API Gateway.

Un prerequisito per creare e modificare la documentazione di un API è che sia già stato creato ilAPI. In questa sezione, utilizziamo PetStoreAPIcome esempio. Per crearne una API utilizzando la console API Gateway, segui le istruzioni riportate inTutorial: 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": "[e-mail]"
       }
     }
   }

   Nota

   Non è necessario codificare la properties mappa in una JSON stringa. La console API Gateway stringe l'oggetto al JSON posto tuo.

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 APIdelle azioni, quindi scegli Aggiorna documentazione. API

   

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

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

2. Seleziona il nome del tuoAPI, quindi sulla API scheda 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.

   

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

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.

   

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

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, selezionate un HTTP verbo.

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, selezionate un HTTP verbo.

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, selezionate un HTTP verbo.

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, selezionate un HTTP verbo.

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

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, selezionate un HTTP verbo.

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

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, selezionate un HTTP verbo.

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

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 impostazione API predefinita, il Error modello fornito con every ha la seguente definizione di 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 API viene esportato, le DocumentationPart sue proprietà sostituiranno 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.

   

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.