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 documento OpenAPI per generare SmartDocs
- Come rigenerare SmartDocs
- Informazioni sui ruoli
- Concessione, modifica e revoca dell'accesso alle risorse
- Creazione e gestione di ruoli personalizzati
Prerequisiti
Questa pagina presuppone che tu abbia già creato il tuo portale.
Informazioni sulla documentazione di riferimento dell'API SmartDocs
Ogni volta che esegui il deployment di un 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 riquadro Prova questa API per interagire con l'API senza uscire dalla documentazione dell'API.Informazioni sui campi utilizzati per generare SmartDocs
Il documento OpenAPI contiene il seguente formato:
swagger: "2.0" info: description: "A simple Google Cloud Endpoints API example." title: "Endpoints Example" version: "1.0.0" host: "echo-api.endpoints.example-project-12345.cloud.goog"
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.description
: il valore della descrizione viene visualizzato in piccolo carattere sotto il titolo nella home page 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.
Il portale Endpoints genera la documentazione di riferimento per ogni singolo endpoint elencato nella sezione paths
del documento OpenAPI. I seguenti estratti provengono dal documento OpenAPI utilizzato per generare la documentazione di riferimento per l'endpoint echo
nell'API "Endpoints Example" nella demo del portale endpoint:
paths: "/echo": post: description: "Echo back a given message." operationId: "echo" produces: - "application/json" responses: 200: description: "Echo" schema: $ref: "#/definitions/echoMessage" parameters: - description: "Message to echo" in: body name: message required: true schema: $ref: "#/definitions/echoMessage" security: - api_key: []
Il parametro per l'endpoint echo
è definito nella seguente sezione:
definitions: echoMessage: type: "object" properties: message: type: "string"
Il file openapi.yaml
completo utilizzato nella demo del portale degli endpoint è incluso nell'esempio di endpoint getting-started
.
Come best practice, includi sempre il campo description
nelle definizioni delle proprietà e in tutte le altre sezioni del documento OpenAPI. Il campo
description
può contenere più righe e supporta
GitHub aromatizzato Markdown.
Ad esempio, crea un elenco puntato sulla home page dell'API in un portale:
swagger: "2.0" info: description: "A simple API to help you learn about Cloud Endpoints. * item 1 * item 2" title: "Endpoints Example" version: "1.0.0" host: "echo-api.endpoints.example-project-12345.cloud.goog"
Rigenerazione di Documenti smart
Per rigenerare la documentazione di riferimento:
Apporta le modifiche al documento OpenAPI.
Esegui di nuovo il deployment del tuo documento OpenAPI (denominato
openapi.yaml
nel seguente comando):gcloud endpoints services deploy openapi.yaml
Aggiorna la pagina del portale.
Scopri di più sul comando
gcloud endpoints services deploy
.