Aggiunta di documentazione personalizzata

Oltre alla documentazione di riferimento dell'API SmartDocs, puoi aggiungere al portale una documentazione personalizzata che potrebbe essere utile per gli utenti dell'API. Anche se non devi fornire agli utenti ulteriori pagine di documentazione, devi aggiornare l'esempio della Guida introduttiva visualizzata nel portale per spiegare come iniziare a utilizzare l'API.

In questa pagina viene descritto come modificare la guida di esempio Guida introduttiva e come creare e visualizzare pagine di documentazione aggiuntive per il tuo portale. Per ogni attività viene fornito il ruolo o i ruoli minimi richiesti per completare l'attività. Per ulteriori informazioni sulle autorizzazioni IAM, consulta quanto segue:

Prerequisiti

La pagina presuppone che tu abbia:

Informazioni sulla documentazione personalizzata

Per visualizzare la documentazione personalizzata nel tuo portale, devi archiviare i file in un repository Git e configurare l'URL al repository Git nella pagina Impostazioni del portale. Puoi aggiungere i file per la documentazione personalizzata a:

  • Un repository privato in Cloud Source Repositories che si trova nello stesso progetto Google Cloud della tua API.
  • Un repository pubblico in GitHub o Bitbucket.

Affinché il portale Cloud Endpoints possa trovare e visualizzare la documentazione personalizzata, i file e le cartelle nel repository devono avere una struttura specifica. Nella directory principale del repository è necessaria una cartella con il nome del servizio Cloud Endpoints. Se necessario, puoi creare sottocartelle aggiuntive. La barra di navigazione a sinistra contiene link alle cartelle e ai file. Per saperne di più, consulta Struttura della directory obbligatoria

Utilizzi Markdown per modificare i contenuti nella Guida introduttiva e per scrivere i contenuti per pagine di documentazione aggiuntive. Il portale degli endpoint segue le specifiche CommonMark e l'estensione tabella della specifica GitHub Flavored Markdown.

Puoi anche aggiungere immagini al tuo repository e farvi riferimento dai file Markdown.

Iniziare ad aggiornare la documentazione personalizzata

Per iniziare, ti consigliamo di clonare il repository endpoints-developer-portal-sample-content su GitHub, che contiene i seguenti file:

  • Getting Started.md: il file Markdown che include i contenuti della pagina Per iniziare di esempio visualizzata nel portale.
  • Example Page.md: un file di esempio per iniziare a utilizzare Markdown.
  • navigation.yaml: un file che descrive l'ordine di pagine e cartelle nella barra di navigazione sinistra del portale.

  • add_example_page: uno script che:

    • Crea un repository Git in Cloud Source Repositories nel tuo progetto Google Cloud.
    • Crea un repository Git locale nella cartella default-content-repo.
    • Crea una cartella con lo stesso nome del nome di servizio endpoint e crea una sottocartella denominata Guides.
    • Aggiunge alla cartella Guides i file chiamati Example Page.md e Getting Started.md.
    • Aggiunge Example Page al file navigation.yaml.
    • Esegue il commit e il push di queste modifiche nel repository Git appena creato in Cloud Source Repositories.

    Esistono due versioni dello script:

    • Per gli utenti Linux e Mac, c'è add_example_page.sh (Bash Shell).
    • Per gli utenti Windows, è disponibile add_example_page.ps1 (PowerShell).

    L'esecuzione dello script è facoltativa. Se preferisci, puoi creare un repository manualmente in Cloud Source Repositories o in un repository GitHub o Bitbucket pubblico. Devi configurare la struttura di directory richiesta per la documentazione personalizzata.

    Prima di eseguire lo script, consulta la documentazione di prezzi e quote per Cloud Source Repositories. Se esegui lo script e poi decidi di utilizzare un repository GitHub o Bitbucket pubblico, puoi eliminare il repository da Cloud Source Repositories.

Scarica i file di base della documentazione personalizzata

In questa sezione viene descritto come eseguire la configurazione in modo da poter eseguire lo script add_example_page.

Per recuperare i file di base della documentazione personalizzata:

  1. Abilita l'API Cloud Source Repositories:

    1. In API e servizi, vai alla pagina Libreria API.

      Vai alla libreria di API

    2. Dall'elenco dei progetti, seleziona il progetto in cui si trova la tua API.

    3. Cerca l'API Cloud Source Repositories e fai clic sulla relativa scheda per visualizzare la pagina delle informazioni.

    4. Fai clic su Abilita.

  2. Assicurati che l'interfaccia a riga di comando gcloud sia autorizzata ad accedere ai dati e ai servizi:

    gcloud auth login

  3. Imposta il progetto predefinito. Nel comando seguente, sostituisci YOUR_PROJECT_ID con l'ID del progetto Google Cloud in cui hai creato l'API Endpoints:

    gcloud config set project YOUR_PROJECT_ID

  4. Scarica i contenuti, la configurazione e gli script di esempio:

    git clone https://github.com/GoogleCloudPlatform/endpoints-developer-portal-sample-content

  5. Passa alla directory che contiene lo script:

    cd endpoints-developer-portal-sample-content/scripts

  6. Visualizzare il nome del servizio Endpoints:

    gcloud endpoints services list

  7. Esegui lo script con il nome del servizio Endpoints:

    • Utenti Linux e Mac: ./add_example_page.sh SERVICE_NAME
    • Utenti Windows: add_example_page.ps1 SERVICE_NAME

    Al termine dello script, gli URL vengono stampati nelle seguenti posizioni:

    • Le impostazioni del portale della tua API.

    • Il tuo URL Git. Si tratta dello stesso URL visualizzato nel campo URL clone della pagina Cloud Source Repositories.

  8. Sincronizza il repository con il portale:

    1. Evidenzia e copia il primo URL, quindi incollalo nella barra degli indirizzi del browser per andare alla pagina Impostazioni.
    2. Segui le istruzioni di accesso per passare alla pagina Impostazioni della tua API. Se disponi di più account, assicurati di scegliere quello che appartiene al progetto Google Cloud proprietario dell'API.
    3. Evidenzia e copia l'URL clone per il tuo repository Git, quindi incollalo nel campo Impostazioni contenuti personalizzati.
    4. Fai clic su Sync (Sincronizza).
    5. Fai clic su Salva.
    6. Per tornare alla pagina di destinazione della documentazione dell'API, fai clic sulla barra del titolo.

    Nella barra di navigazione a sinistra, fai clic su Pagina di esempio per visualizzare i contenuti.

  9. Sfoglia i contenuti del repository appena creato. In Google Cloud Console, vai alla pagina Source Repositories > Codice sorgente del progetto.

    Vai al browser del codice sorgente

    Il browser del codice sorgente mostra una visualizzazione di directory dei contenuti del repository al livello di commit più recente. Per ulteriori informazioni, consulta la pagina Sfogliare i repository.

Modificare la documentazione personalizzata

Ora che hai la documentazione personalizzata in Cloud Source Repositories, puoi modificare i contenuti e aggiungere o eliminare file e cartelle in base alle esigenze. Se non hai mai utilizzato Git, la documentazione di Git contiene la documentazione di riferimento e link a libri e video.

Modifica i contenuti Getting Started

Per modificare i contenuti Getting Started:

  1. Partendo dalla directory principale del repository Git locale, vai alla cartella con lo stesso nome del servizio Endpoints. Ad esempio:

    cd example-api.example.com

  2. Vai alla cartella che contiene Getting Started.md:

    cd Guides

  3. Apri Getting Started.md in un editor di testo.

  4. Modifica i contenuti in base alle tue esigenze per aiutare gli utenti a iniziare a utilizzare l'API.

  5. Salva il file.

  6. Esegui il commit delle modifiche:

    git commit -a -m "updated getting started"

  7. Esegui il push delle modifiche al repository in Cloud Source Repositories:

    git push

  8. Sincronizza i contenuti aggiornati sul tuo portale:

    1. Accedi al portale.
    2. Fai clic su Impostazioni .
    3. Nella pagina Impostazioni, fai clic sulla scheda API e seleziona l'API dall'elenco.
    4. Fai clic su Sync (Sincronizza).
    5. Fai clic su Salva.

    Quando fai clic sul link Getting Started nella barra di navigazione a sinistra, nel Portale endpoint vengono visualizzati i contenuti aggiornati.

Rimuovi Example Page

Per rimuovere Example Page:

  1. Partendo dalla directory principale del repository Git locale, vai alla cartella con lo stesso nome del servizio Endpoints. Ad esempio:

    cd example-api.example.com

  2. Apri il file navigation.yaml in un editor di testo.

  3. Nella sezione ordering, elimina la riga con Example Page.

  4. Salva il file.

  5. Rimuovi il file Example Page.md da Git:

    git rm ‘Guides/Example Page.md'

  6. Esegui il commit delle modifiche:

    git commit -a -m "removed example page"

  7. Esegui il push delle modifiche al repository in Cloud Source Repositories:

    git push

  8. Sincronizza i contenuti aggiornati sul tuo portale:

    1. Accedi al portale.
    2. Fai clic su Impostazioni .
    3. Nella pagina Impostazioni, fai clic sulla scheda API e seleziona l'API dall'elenco.
    4. Fai clic su Sync (Sincronizza).
    5. Fai clic su Salva.

Example Page non è più disponibile nella barra di navigazione a sinistra.

Rinomina Example Page

Per rinominare Example Page:

  1. Partendo dalla directory principale del repository Git locale, vai alla cartella con lo stesso nome del servizio Endpoints. Ad esempio:

    cd example-api.example.com

  2. Apri il file navigation.yaml in un editor di testo.

  3. Nella sezione ordering, modifica la Pagina di esempio nel titolo della guida. Il nome qui deve corrispondere al nome effettivo del file nella directory Guides.

  4. Salva il file.

  5. Rinomina il file Example Page.md in Git.

    git mv 'Guides/Example Page.md' 'Guides/NEW FILENAME.md'

  6. Modifica i contenuti del file rinominato in base alle tue esigenze.

  7. Esegui il commit delle modifiche:

    git commit -a -m "removed example page"

  8. Esegui il push delle modifiche al repository in Cloud Source Repositories:

    git push

  9. Sincronizza i contenuti aggiornati sul tuo portale:

    1. Accedi al portale.
    2. Fai clic su Impostazioni .
    3. Nella pagina Impostazioni, fai clic sulla scheda API e seleziona l'API dall'elenco.
    4. Fai clic su Sync (Sincronizza).
    5. Fai clic su Salva.

La pagina rinominata viene visualizzata nella barra di navigazione a sinistra.

Struttura di directory obbligatoria

Affinché il portale degli endpoint possa trovare e visualizzare i tuoi contenuti personalizzati, i file e le cartelle nel tuo repository devono essere in una struttura specifica.

Nella directory principale del repository deve essere presente una cartella con il nome del tuo servizio endpoint. Questa struttura offre la possibilità di utilizzare un repository per più API, creando cartelle di livello radice separate per ciascuna API.

Le sottocartelle all'interno della cartella del servizio consentono di raggruppare le pagine correlate in una sezione e possono contenere ulteriori sottocartelle. Il titolo delle cartelle e dei nomi di file viene utilizzato nella navigazione. Ad esempio, un file denominato Getting Started.md viene visualizzato nella barra di navigazione sinistra come Getting Started. All'interno della cartella denominata dal nome del tuo servizio Endpoints, devi avere un file denominato navigation.yaml. Questo file indica come vuoi che i tuoi contenuti vengano visualizzati nella barra di navigazione a sinistra nel portale. Quello predefinito ha il seguente aspetto:

ordering:
- Introduction
- Guides
- API Reference
- Resources

folders:
  Guides:
    ordering:
    - Getting Started
    - Example Page

Il primo elenco ordering specifica l'ordine in cui vuoi che le voci vengano visualizzate in quel livello. Ad esempio, il file navigation.yaml predefinito specifica che la pagina Introduction viene visualizzata per prima, seguita dalla sezione Guides e così via.

Introduction, API Reference e Resources sono sezioni speciali e non devi rimuoverle da navigation.yaml, ma puoi modificare il loro ordine.

Ogni cartella e pagina deve avere una configurazione corrispondente all'interno della configurazione folders del genitore in navigation.yaml. Se omessa, la pagina o la cartella non viene visualizzata nel portale. Ad esempio, nel file navigation.yaml predefinito, la chiave folders contiene una sottochiave denominata Guides perché esiste una cartella con lo stesso nome.

Aggiungi immagini

Puoi aggiungere immagini al repository Git di contenuti personalizzati e farvi riferimento nei tuoi file Markdown. Se inserisci le immagini e tutti i file di Markdown che fanno riferimento a essi nella stessa directory del nome del servizio Endpoints, puoi fare riferimento alle immagini con un URL relativo (che inizia con un /).

Ad esempio, supponiamo che tu abbia la seguente struttura di directory:

~/example-api.example.com/
    get-started.md
    images/
        example.jpg

Puoi aggiungere l'immagine images/example.jpg a get-started.md con il seguente markup:

    ![alt-text](/images/example.jpg "Optional title")

Puoi aggiungere immagini ospitate altrove, utilizzando la sintassi Markdown standard e l'URL completo dell'immagine:

    ![alt-text](https://example.com/image.png "Optional title")

Il portale supporta i seguenti tipi di immagini:

  • BMP
  • GIF
  • JPEG
  • PNG
  • TIFF
  • WEBP

Limiti per i contenuti personalizzati

Il portale presenta le seguenti limitazioni relative ai contenuti personalizzati:

  • Massimo 200 pagine Markdown per API.
  • Sono consentite massimo 200 immagini per API.
  • Dimensione massima di 4 MiB per immagine.

Passaggi successivi