Aggiornamento di SmartDocs

Prima di fornire l'URL del portale agli utenti della tua API, assicurati che la documentazione di riferimento dell'API SmartDocs sia corretta e che l'API si comporti come descritto. Se testi la documentazione di riferimento generata e la verifica, potresti notare alcune modifiche.

In questa pagina vengono descritti:

Documentazione di riferimento dell'API SmartDocs
In che modo SmartDocs utilizza i campi del file openapi.json creato da Cloud Endpoints Frameworks per generare i documenti
Come rigenerare SmartDocs Per ogni attività, viene fornito il ruolo (o i ruoli) minimo richiesto per completare l'attività. Per ulteriori informazioni sulle autorizzazioni IAM, consulta quanto segue:

Prerequisiti

Questa pagina presuppone che tu abbia già creato il tuo portale.

Informazioni sulla documentazione di riferimento dell'API SmartDocs

Quando aggiungi la gestione delle API come descritto di seguito:

Endpoints Frameworks crea un documento OpenAPI per l'API. Ogni volta che esegui il deployment del documento OpenAPI nel tuo servizio Endpoints, SmartDocs genera la documentazione di riferimento dell'API per il portale. L'interfaccia utente di SmartDocs si basa su Angular Material, una libreria all'avanguardia per i componenti dell'interfaccia utente. Gli sviluppatori possono esaminare la documentazione di riferimento dell'API SmartDocs e utilizzare il widget Prova questa API per interagire con l'API senza uscire dalla documentazione dell'API.

Informazioni sui campi utilizzati per generare SmartDocs

Quando aggiungi la gestione delle API come descritto di seguito:

Endpoints Frameworks crea un documento OpenAPI in formato JSON per la tua API. Quando esegui il deployment del documento OpenAPI (utilizzando gcloud endpoints services deploy), SmartDocs genera la documentazione di riferimento dell'API aggiornata per il tuo portale, basata sul documento OpenAPI creato da Endpoints Frameworks.

Endpoints Frameworks non include le descrizioni nel documento OpenAPI che crea per la tua API. Prima di fornire l'URL del tuo portale agli utenti della tua API, ti consigliamo di aggiungere descrizioni all'API, ai metodi e ai parametri nel documento OpenAPI.

Se non hai mai utilizzato OpenAPI, inizia con il sito web di Swagger di base, che fornisce un documento OpenAPI di esempio e spiega brevemente ogni sezione del file. Per informazioni più dettagliate, consulta la specifica di OpenAPI.

Come descritto nella sezione Metadati, il valore del campo description può contenere più righe e supporta Markdown aromatizzato di GitHub.

Per aiutare gli utenti a capire come utilizzare i metodi nella tua API, come best practice, aggiungi un campo description alla sezione Parametri e al corpo della richiesta.

Il documento OpenAPI include i seguenti elementi:

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "example-project-12345.appspot.com"
 },
 "host": "example-project-12345.appspot.com",

I valori per questi campi vengono visualizzati come segue nel portale:

title: il valore del titolo viene visualizzato nella home page del portale nella sezione che elenca le API nel progetto, nella home page dell'API (con la parola documentazione aggiunta) e nella barra del titolo dell'API.
host: il valore dell'host (che è anche il nome del servizio Endpoint) viene visualizzato nella home page del portale nella sezione che elenca le API nel progetto e nella pagina Impostazioni nell'elenco a discesa visualizzato nella scheda API.
version: il numero di versione principale viene utilizzato nell'URL del portale dell'API.

Ti consigliamo di modificare il valore nel campo title e aggiungere un campo description per l'API. Ad esempio:

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "Endpoints Frameworks Example",
  "description": "A simple Cloud Endpoints Frameworks API example."
 },
 "host": "example-project-12345.appspot.com",

Rigenerazione di Documenti smart

Autorizzazioni richieste per questa attività

Per rigenerare SmartDocs, esegui il deployment della configurazione degli endpoint aggiornata. Il ruolo Editor di configurazione del servizio concesso per il servizio dispone delle autorizzazioni minime richieste per eseguire nuovamente il deployment della configurazione degli endpoint. Per informazioni su come assegnare questo ruolo, consulta l'articolo Concessione e revoca dell'accesso all'API.

Per rigenerare la documentazione di riferimento:

Apporta le modifiche al file openapi.json generato dagli endpoint.

Esegui di nuovo il deployment di openapi.json:

gcloud endpoints services deploy openapi.json

Aggiorna la pagina del portale.
Salva il file openapi.json modificato in una posizione in cui non possa essere sovrascritto se successivamente devi rigenerare il file openapi.json. Se apporti modifiche all'API e rigenera il file openapi.json, devi unire le modifiche nella risorsa openapi.json appena generata con le modifiche che hai apportato in precedenza.

Scopri di più sul comando gcloud endpoints services deploy.