Aggiornamento di SmartDocs

OpenAPI   |  gRPC

A partire dal 21 marzo 2022, il portale Cloud Endpoints è stato ritirato. Il portale Cloud Endpoints non sarà più disponibile dopo il 21 marzo 2023. Questa modifica non influisce sul traffico API gestito da Cloud Endpoints. Per maggiori informazioni, consulta la pagina relativa al ritiro delle funzionalità.

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

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:

• 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

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:

1. Apporta le modifiche al documento OpenAPI.

2. Esegui di nuovo il deployment del tuo documento OpenAPI (denominato openapi.yaml nel seguente comando):

   gcloud endpoints services deploy openapi.yaml
   

3. Aggiorna la pagina del portale.

Scopri di più sul comando gcloud endpoints services deploy.