Utilizzo di SmartDocumenti per documentare le API

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

di Gemini Advanced.

SmartDocs ti consente di documentare le tue API sul portale per sviluppatori di Drupal 7 in un modo la documentazione dell'API è completamente interattiva. Grazie alla documentazione interattiva, gli utenti del portale possono:

  • Scopri di più sulle tue API
  • Invia una richiesta in tempo reale all'API
  • Visualizzare una risposta in tempo reale restituita dall'API

Creando una documentazione interattiva sulle tue API, consenti agli utenti del portale di imparare, testare e valutare le API.

L'API Edge Management è un'API RESTful che consente di accedere ai servizi API utilizzando qualsiasi un client HTTP. Apigee utilizza SmartDocs per creare documentazione interattiva per la gestione perimetrale tramite Google Cloud CLI o tramite l'API Compute Engine. Consulta la documentazione dell'API qui.

Esempio del portale SmartDocs

Per utilizzare SmartDocs, devi avere un portale Apigee Developer Services. Per ulteriori informazioni, vedi Creazione di uno sviluppatore portale.

Nella home page del portale per gli sviluppatori, fai clic su API nella barra di navigazione in alto per consulta la pagina della documentazione dell'API.

Sul portale sono documentate due API: Hello World e Pet Store Example.

L'API Hello World è stata creata dalla simulazione OpenAPI di destinazione Specifica: mocktarget.yaml. Per ulteriori informazioni, visita https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.

L'API Pet Store Example è stata creata dalla demo classica del negozio di animali.

Esplora l'API Hello World:

  1. Fai clic su API Hello World. Viene visualizzata la pagina di riepilogo dell'API Hello World:
  2. Fai clic su Visualizza conferma API. SmartDocs per questa risorsa è visualizzato:
  3. Fai clic su Invia questa richiesta.
  4. Visualizza la risposta restituita: 
    HTTP/1.1 200 OK
Connection:
keep-alive
Content-Length:
18
Content-Type:
text/html; charset=utf-8
Date:
Tue, 21 Jun 2016 21:49:32 GMT
ETag:
W/"12-Jb9QP1bUxNSmZkxQGt5KLQ"
X-Powered-By:
Apigee
<H2>I <3 APIs</H2>
  5. Fai clic sulla scheda Richiesta per visualizzare la richiesta o sul cURL premi Tab per visualizzare la chiamata cURL corrispondente.

Come documentare le API utilizzando SmartDocs

SmartDocumenti rappresenta le API utilizzando un modello, in cui il modello contiene tutte le informazioni sulle API. Il portale estrae informazioni sulle API dal modello le pagine della documentazione sul portale come nodi Drupal, dove ogni nodo Drupal corrisponde a una pagina di documentazione sul portale.

I passaggi generali che segui per utilizzare SmartDocs sono:

  1. Configura il modulo Drupal SmartDocs sul portale.
  2. Crea un modello di Documenti Smart.
  3. Aggiungere API al modello da un file WADL, OpenAPI (in precedenza Swagger) o manualmente.
  4. Esegui il rendering del modello come una raccolta di nodi Drupal. Ogni nodo Drupal contiene informazioni su una singola API. Ad esempio, se una risorsa nell'API supporta sia un POST e una richiesta PUT, SmartDocs crea un nodo Drupal separato per POST e PUT.
  5. Pubblica i nodi Drupal. Dopo la pubblicazione, gli utenti del portale possono visualizzare a interagire con l'API.
  6. Modifica i nodi Drupal prima o dopo la loro pubblicazione. Puoi modificare i nodi Drupal utilizzando l'editor Drupal o modificando il file WADL originale oppure specifica OpenAPI. Quando hai terminato di modificare il file WADL o la specifica OpenAPI, importa nel modello come nuova revisione, quindi esegui il rendering e pubblica le modifiche.
  7. Attiva TLS. Dato che SmartDocs può inviare credenziali di autenticazione ai tuoi durante l'invio di una richiesta alle API, devi abilitare TLS sul portale per assicurarti che le credenziali siano sicure. Negli ambienti di produzione e test del portale, Apigee fornisce il certificato TLS necessario per effettuare richieste https://. Tuttavia, prima di andarci di online con il tuo portale, devi ottenere il tuo certificato TLS e abilitare TLS. Per ulteriori informazioni, vedi L'utilizzo di TLS portale.

Informazioni su modelli e modelli SmartDoc

Quando crei un modello nel tuo portale, questo viene effettivamente archiviato in Edge dell'organizzazione, non in Drupal. Un modello è un grande blocco di JSON con un nome interno (come "my-smartdocs-api") e definisce la struttura di un'API. Il tuo portale, invece, esegue il rendering del modello in HTML e fornisce un'interfaccia di modifica per il modello. Eventuali aggiornamenti all'API nel portale vengono automaticamente respinte al modello di origine.

Archiviati nell'organizzazione

Archiviato in Drupal

modelli

templates

Nodi Drupal con funzionalità di modifica

Supponi di avere più portali nella tua organizzazione (ad esempio, dev, stage produzione). In Pantheon, sposti un portale da un ambiente all'altro. Ogni istanza del portale sembra contenere il proprio modello, ma tutti fanno effettivamente riferimento un modello di machine learning. Se modifichi l'API in dev, il modello viene aggiornato e le modifiche vengono visualizzate in produzione. Allo stesso modo, se elimini un modello in dev, l'origine viene eliminata e non è più disponibile in e produzione.

I modelli controllano l'aspetto dei tuoi SmartDocumenti e dei modelli (regolati da manubri e file CSS) vengono archiviati insieme a ogni istanza del portale. Quindi, in teoria, ogni portale può usare un modello univoco per ogni modello. Tuttavia, una delle comodità del framework di rendering è che un modello predefinito (quello predefinito di Apigee o un modello fornito da te) viene automaticamente applicati a ciascun modello.

Il seguente diagramma mostra la relazione tra modelli e portali. Le frecce verdi mostrano la sincronizzazione automatica.

Il seguente comando cURL elenca tutti i modelli della tua organizzazione:

curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u edge_org_admin@example.com

Configurazione del modulo SmartDocs

Apigee ha implementato SmartDocs come modulo Drupal personalizzato. Utilizza la seguente procedura per configurare il modulo SmartDocs.

Per configurare il modulo SmartDocs:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Moduli nel menu di amministrazione di Drupal. L'elenco di tutte vengono visualizzati i moduli Drupal installati.
  3. Attiva il modulo SmartDocs.
  4. Salva la configurazione.
  5. Seleziona Moduli nel menu di amministrazione di Drupal.
  6. Seleziona SmartDocs -> autorizzazioni e assicurati che l'opzione "Esegui amministrazione per il modulo SmartDocs" per "Amministratore" il ruolo sia abilitato.
  7. Seleziona Configurazione > Portale per sviluppatori nell'amministrazione Drupal o dal menu Fogli Google.
  8. Imposta Timeout connessione e Timeout richiesta su 16. secondi.
  9. Salva la configurazione.
  10. Configura le impostazioni degli URL:
    1. Seleziona Configurazione > Ricerca e metadati > Alias URL > Impostazioni dal menu Drupal.
    2. Imposta Lunghezza massima alias e Componente massima fino a 255.
    3. Espandi Punteggiatura.
    4. Per parentesi graffa aperta ({) e Parentesi graffa chiusa (}), seleziona Nessuna azione (non sostituire).
    5. Fai clic su Salva configurazione.
  11. Se il tuo portale per gli sviluppatori verrà esposto agli utenti di una rete interna senza accesso a internet o se un sottoinsieme delle tue API si trova su una rete privata, configura l'API SmartDocs come segue:
    1. Seleziona Configurazione > SmartDocumenti in Drupal Administration o dal menu Fogli Google.
    2. Espandi Impostazioni avanzate.
    3. Aggiorna il campo URL del proxy SmartDocs come segue: <host>/smartdocs/v1/sendrequest.
      La guida in linea dovrebbe fornire il valore richiesto per il tuo ambiente. Ad esempio:
      https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest

      L'impostazione predefinita di questo campo è https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest
    4. Fai clic su Salva configurazione.

Creazione di un modello

Un modello contiene tutte le informazioni sulla rappresentazione dell'API. Puoi definire più modelli sul portale per supportare API diverse o raggruppa tutte le API in un'unica un modello di machine learning.

Ogni modello specifica un nome interno univoco che definisce anche l’URL di base del dei nodi Drupal generati. L'URL di ogni nodo Drupal ha il seguente formato:

http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>

dove:

  • drupalBasePath: l'URL di base del tuo portale.
  • internalName: nome interno del modello.
  • httpMethod - Il metodo HTTP dell'API, ad esempio get, put, post o eliminare.
  • resourcePath: il percorso della risorsa.

Ad esempio, se specifichi il nome interno come "miomodello", l'URL per l'URL Nodo Drupal per una richiesta GET a una risorsa denominata '/books' è:

http://prod-myco.devportal.apigee.com/mymodel/apis/get/books

Per creare un modello

Quando crei un modello, questo viene archiviato nella tua organizzazione Edge come origine per l'API alla struttura del centro di costo. Per ulteriori informazioni, consulta Informazioni sui modelli SmartDoc e modelli.

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Contenuti > SmartDocumenti nell'amministrazione Drupal o dal menu Fogli Google.
  3. Seleziona Nuovo modello nella parte superiore della pagina.
  4. Completa i seguenti campi:
    • Nome: il nome del modello che verrà visualizzato sul sito.
    • Nome interno: mentre digiti il Nome, lo spazio viene visualizzato il tuo nome utente. Il nome interno del modello che deve essere univoco tra tutti i modelli. Il nome interno deve contenere solo lettere minuscole, numeri e trattini, senza spazi. Seleziona Modifica per modificare questo nome.
    • Descrizione: una descrizione del modello.
  5. Seleziona Crea modello.

Dopo aver creato il modello, si aprirà la pagina del modello. Da qui puoi utilizzare dal menu a discesa Operazioni bx per:

  • Importa un file WADL che descriva l'API o specifica l'URL di un file OpenAPI. Specifica che descrive l'API.
  • Aggiungi revisione al modello
  • Modifica le Impostazioni del modello, inclusi i fogli di stile utilizzati dalla un modello di machine learning.
  • Esporta il modello in un file.
  • Elimina il modello.

Aggiunta di API a un modello

Per aggiungere le API a un modello, puoi:

  • Importazione di un file WADL contenente la definizione dell'API
  • Importazione di una specifica OpenAPI (OpenAPI 2.0 o 1.2)
  • Creazione manuale di risorse e metodi

Puoi anche importare un file JSON SmartDocs in un modello. Questo file viene in genere creato esportando un modello esistente, modificando il file e infine importando gli aggiornamenti. Per ulteriori informazioni, consulta "Esportazione e importazione di un modello" di seguito.

Video: guarda un breve video per scoprire come aggiungere API a un modello SmartDocs importando una specifica OpenAPI.

Importare un file WADL

Dopo aver creato correttamente un modello, importa un file WADL che descriva l'API. Ogni evento ogni volta che importi un file WADL, viene creata automaticamente una nuova revisione del modello.

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Contenuti > SmartDocumenti in Drupal menu di amministrazione.
  3. Seleziona il modello da aggiornare.
  4. In Operazioni, seleziona Importa.
  5. Seleziona WADL nel menu a discesa Scegli formato della sezione Pagina di importazione di SmartDocs.
  6. Seleziona File o URL nella sezione Carica. Menu a discesa Tipo.
    1. Se selezioni File, vai al file WADL.
    2. Se selezioni URL, specifica l'URL del file WADL.
  7. Fai clic su Importa per importarlo nel modello. Ora puoi eseguire il rendering del modello.
  8. Si aprirà la pagina delle informazioni sul modello, dove potrai eseguire il rendering un modello di machine learning.

Importa una OpenAPI Specifiche

Dopo aver creato correttamente un modello, puoi importare un OpenAPI (ex Swagger) Specifiche. Edge supporta OpenAPI versione 1.2 e 2.0.

OpenAPI utilizza file contenenti oggetti JSON per descrivere un'API. Ogni volta che importi specifica OpenAPI, viene creata automaticamente una nuova revisione del modello.

Per importare una specifica OpenAPI:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Contenuti > SmartDocumenti Menu di amministrazione di Drupal.
  3. Seleziona il modello da aggiornare.
  4. In Operazioni, seleziona Importa.
  5. Seleziona Swagger JSON o Wagger YAML nella Menu a discesa Scegli formato nella pagina di importazione di SmartDocs.
  6. Seleziona File o URL nella Menu a discesa Tipo di caricamento (devi selezionare URL per OpenAPI 1.2).
    1. Se selezioni File, passa alla sezione OpenAPI Specifiche.
    2. Se selezioni URL, specifica l'URL dell'API OpenAPI Specifiche.
  7. Fai clic su Importa per importarlo nel modello.
  8. Si aprirà la pagina delle informazioni sul modello, dove potrai eseguire il rendering un modello di machine learning.

Creare risorse manualmente e metodi

Se non disponi di un file WADL o di una specifica OpenAPI che rappresenta l'API, puoi aggiungere manualmente le API al modello. Inoltre, se utilizzi un file WADL o una specifica OpenAPI per creare il modello, puoi utilizzare questa procedura per modificare le API, inclusa l'aggiunta di nuove API, per l'importazione.

Per aggiungere manualmente un'API:

  1. Crea una nuova revisione del modello.

    Quando crei la revisione, specifichi l'unico percorso di base di tutte le API nel modello, il che significa che tutte le API in un modello hanno lo stesso percorso di base. Ad esempio, specifica il percorso di base come:

    https://myCompany.com/v1

    Le risorse aggiunte al modello estendono il percorso di base.
  2. Definisci una o più risorse per il modello. Il percorso della risorsa si combina con il percorso di base della revisione del modello per specificare l'URL completo della risorsa. Ad esempio, se la tua risorsa definisce un percorso di "/login", l'URL completo della risorsa è:

    https://myCompany.com/v1/login
  3. Definisci uno o più metodi per ogni risorsa. Un metodo specifica il verbo HTTP che può essere richiamati su una risorsa. Ad esempio, per "/login" risorsa, supporti POST per l'accesso e DELETE per disconnessione. Questa risorsa non supporta altri verbi HTTP, come PUT o GET. Definisci quindi due metodi per la risorsa: uno per POST e uno per DELETE.

    Il metodo utilizza l'URL della risorsa della risorsa padre. Di conseguenza, tutti i metodi con lo stesso Gli URL sono definiti in una singola risorsa in SmartDocs.

Come regola generale:

  • Creare un modello SmartDocs diverso per ogni percorso di base univoco nell'API.
  • Definisci una risorsa SmartDocs diversa per ogni risorsa unica nell'API.
  • Definire un metodo SmartDocs diverso per ogni verbo HTTP supportato da una risorsa.

Creazione di una nuova revisione di un modello

Puoi aggiungere una risorsa solo a una revisione esistente di un modello. Se il modello ha già revisione, puoi aggiungere la tua risorsa. Se il modello è nuovo e non ha revisioni, crea un nuovo revisione.

Per creare una nuova revisione di un modello:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Contenuti > SmartDocs in il menu di amministrazione di Drupal.
  3. Seleziona Aggiungi revisione per il modello da aggiornare. in Operazioni.
  4. Nella pagina Add API Revision (Aggiungi revisione API), inserisci le informazioni seguenti:
      .
    • Nome visualizzato: il nome della revisione così come viene visualizzato nella portale.
    • ID versione: un breve identificatore della revisione.
    • Descrizione: una descrizione della revisione.
    • URL di base: l'URL di base di tutte le API nella revisione del modello. R può usare diversi URL di base per ogni revisione. Ad esempio, includi una versione nell'URL di base. Per la prima revisione del modello, l'URL di base è:
      https://myCompany.com/v1
      Per la revisione successiva, l'URL di base potrebbe essere:
      https://myCompany.com/v2
  5. Seleziona Aggiungi revisione. Si aprirà la pagina di revisione del modello. Ora puoi definire le risorse sul modello.

Definizione di una risorsa

Una risorsa specifica l'URL completo di un'API. Quando definisci una risorsa, specifichi percorso della risorsa, che è combinato con l'URL di base nella revisione del modello per creare l'URL completo della risorsa.

Per definire una risorsa:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Contenuti > SmartDocs in il menu di amministrazione di Drupal.
  3. Per il modello che desideri aggiornare, in Operazioni, seleziona API Revisioni per visualizzare tutte le revisioni di un modello.
  4. Seleziona una revisione da modificare.
  5. Nella pagina della revisione, seleziona Aggiungi risorsa dal menu a discesa.
  6. Nella pagina Add Resource (Aggiungi risorsa), inserisci le informazioni seguenti:
      .
    • Nome visualizzato: il nome della risorsa.
    • Percorso: il percorso della risorsa, che inizia con "/". Il valore di Il percorso viene combinato con l'URL di base della revisione del modello per creare l'URL completo della risorsa.
    • Descrizione: una descrizione della risorsa.
    • Parametri: se vuoi, inserisci l'oggetto JSON che definisce ciascun parametro sulla risorsa. Questi parametri sono descritti di seguito.
  7. Seleziona Aggiungi risorsa. Si aprirà la pagina del modello. Ora puoi e definire metodi sulla risorsa.

Facoltativamente, puoi aggiungere parametri alla risorsa, ad esempio modello, query e intestazione parametri. Tutti i parametri della risorsa vengono ereditati da qualsiasi metodo definito su quella risorsa. Pertanto, se definisci un parametro di query sulla risorsa, tutti i metodi aggiunti alla risorsa deve supportare quel parametro di query.

In alternativa, puoi definire parametri su un metodo. Ad esempio, un metodo POST potrebbe supportare parametri di query non supportati da un metodo DELETE. Pertanto, aggiungi eventuali parametri specifico di un metodo quando lo definisci, come descritto di seguito.

L'immagine seguente mostra una pagina SmartDocs esistente per Approvazione o revoca dell'API Apigee Developer App con ogni tipo di parametro evidenziato:

Ogni tipo di parametro è definito da un oggetto JSON:

Tipo

Oggetto JSON

Note

Modello

{
"dataType": "stringa",
"defaultValue": "",
"description": "Il nome dell'organizzazione.",
"name": "nome_organizzazione",
"required": true,
"type": "MODELLO"
}

I parametri del modello sono sempre obbligatori, quindi imposta required su true e ometti il valore su defaultValue (Valore predefinito).

Il valore description appare in un popup quando l'utente passa il mouse sopra l'URL in una pagina SmartDocs.

Query

{
"dataType": "stringa",
"defaultValue": "",
"description": "La posizione.",
"name": "set",
"required": true,
"type": "QUERY"
}

I parametri di query obbligatori possono comunque specificare un defaultValue, ma spesso non è così.

Per i parametri di query facoltativi, imposta required su false e specifica un valore su defaultValue (Valore predefinito).

Intestazione

{
"dataType": "stringa",
"defaultValue": "application/json",
"description": "Specifica come <code>application/json</code>.",
"name": "Tipo di contenuti",
"required": true,
"type": "HEADER"
}

Nota come puoi utilizzare i tag HTML nella descrizione.

Un parametro del modello definisce una variabile nel percorso della risorsa. Ad esempio, definisci due i parametri del modello sulla risorsa. Nota come ogni definizione di parametro nell'array di parametri è separato da una virgola:

[
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the organization name.",
  "name": "org_name",
  "required": true,
  "type": "TEMPLATE"
 },
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the user email.",
  "name": "developer_email",
  "required": true,
  "type": "TEMPLATE"
 }
]

Puoi quindi utilizzare i parametri del modello nella definizione del percorso della risorsa, racchiuso tra "{}". Ad esempio, imposta il percorso su:

/login/{org_name}/{developer_email}

Nella pagina dell'API SmartDocs, l'utente deve modificare l'URL per specificare la porzione org_name e developer_email dell'URL prima possono inviare una richiesta.

Definizione di un metodo

Definisci uno o più metodi per ogni risorsa. La definizione del metodo specifica un verbo HTTP che possono essere richiamati sulla risorsa. Una risorsa può avere un singolo metodo definito più metodi.

Durante la definizione del metodo, specificare tutti i parametri utilizzati dal metodo, tra cui query e parametri dell'intestazione. Consulta la descrizione sopra per le risorse per informazioni sull'aggiunta di parametri a un metodo.

L'immagine seguente mostra una pagina SmartDocs esistente per l'API Apigee Create Developer con ogni area della pagina evidenziata con il valore corrispondente che imposti quando definisci un :

L'immagine successiva mostra la stessa pagina, ma con la descrizione del corpo della richiesta selezionata:

Per definire un metodo:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Contenuti > SmartDocs in il menu di amministrazione di Drupal.
  3. Per il modello che desideri aggiornare, in Operazioni, seleziona API Revisioni per visualizzare tutte le revisioni di un modello.
  4. Seleziona una revisione da modificare.
  5. Nella pagina della revisione, seleziona Aggiungi metodo dal menu a discesa per uno degli le risorse.
  6. Nella pagina Edit Method (Metodo di modifica), inserisci le seguenti informazioni:
      .
    • Nome visualizzato: il nome dell'API, che diventa anche il titolo del pagina Drupal per l'API.
    • Descrizione: descrivi l'API.
    • Metodo Verbo: il tipo di verbo HTTP.
    • Schemi di sicurezza: specifica l'eventuale modalità di autenticazione per il . Per ulteriori informazioni, consulta Configurare l'autenticazione SmartDocs del testo.
    • Tipo di contenuti: il tipo di contenuti della richiesta e della risposta. Consulta le di seguito sulla configurazione dei diversi metodi di autenticazione.
    • Parametri: (facoltativo) eventuali parametri di query o intestazione per il metodo. Per saperne di più, consulta la descrizione riportata sopra per aggiungere un parametro a una risorsa.
    • Documentazione del corpo della richiesta: (facoltativo) descrivi il corpo della richiesta. PUBBLICA e i metodi PUT accettano il corpo della richiesta. Puoi utilizzare quest'area per descriverlo. Se ometti questo messaggio il valore, il link Descrizione nel Corpo della richiesta viene omesso dalla pagina SmartDocs generata.
    • Esempio di corpo della richiesta: (facoltativo) mostra un esempio di corpo della richiesta, di solito come oggetto JSON o XML. Per i verbi POST e PUT, il Corpo della richiesta Nell'ambito di ogni richiesta viene passato un esempio. Gli utenti della pagina SmartDocs modificano questo documento esempio prima di inviare una richiesta all'API. Se ometti questo valore, il valore Il link Valore in Corpo della richiesta viene omesso dalla pagina SmartDocs generata.
    • Tag: un array di tag associati all'API. SmartDocs utilizza i tag per raggruppano insieme API simili. Ad esempio, puoi applicare il tag "Statistiche" a tutte le API sulle statistiche. Puoi raggruppare le API da risorse diverse in un unico tag. se usano tutti lo stesso tag.
  7. Seleziona Aggiungi metodo. Si aprirà la pagina del modello. Ora puoi eseguire il rendering e pubblicare il metodo.

Rendering di un modello

Dopo aver aggiunto le API a un modello, puoi eseguire il rendering del modello. Il rendering converte il valore descrizione dell'API nei nodi Drupal. Al termine del rendering, avrai un solo Drupal per ogni API, dove ogni nodo Drupal corrisponde a una pagina HTML.

Puoi scegliere di eseguire il rendering dell'intero modello contemporaneamente o selezionare singole API per per il rendering delle immagini.

Per eseguire il rendering di un modello:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Contenuti > SmartDocs in il menu di amministrazione di Drupal.
  3. Per il modello di cui desideri eseguire il rendering, seleziona Revisioni API in Operazioni.
  4. Seleziona la revisione di cui vuoi eseguire il rendering. Puoi eseguire il rendering dei nodi solo da una singola revisione del modello.
  5. Seleziona i metodi di cui eseguire il rendering.
  6. Seleziona Render Nodes (Nodi di rendering) dall'Update (Aggiorna) opzioni.
  7. Fai clic su Aggiorna.
  8. Viene visualizzata una schermata di caricamento per visualizzare l'avanzamento del rendering dei nodi.
    Dopo il rendering dei nodi, l'ID del nodo Drupal per ogni API viene visualizzato nella sezione Colonna Associazione dei nodi del modello. Fai clic sul link nella sezione Nodo Associazione per vedere il nodo sottoposto a rendering.

Anziché selezionare Nodi di rendering,puoi selezionare Rendering e pubblichi nodi per eseguire il rendering e pubblicare immediatamente le API come nodo Drupal.

Pubblicazione dei nodi

Un nodo non è visibile agli utenti del portale finché non viene pubblicato. Se vuoi, puoi scegliere pubblicare nodi durante il processo di rendering. Se scegli di non pubblicare i nodi, devi pubblicarli manualmente al termine del rendering.

Per pubblicare un nodo:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Contenuti > SmartDocs in il menu di amministrazione di Drupal.
  3. Per il modello da pubblicare, seleziona Revisioni API in Operazioni.
  4. Seleziona la revisione da pubblicare. Puoi pubblicare nodi solo da una singola revisione del modello.
  5. Seleziona i metodi per la pubblicazione.
  6. Seleziona i nodi nella revisione da pubblicare.
  7. Seleziona Pubblica nodi da Aggiorna opzioni.
  8. Fai clic su Aggiorna.
  9. Accedi al nodo selezionando il relativo ID in Associazione nodo colonna.

Per impostazione predefinita, l'URL Drupal a un nodo API pubblicato è nel formato: http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>. Utilizza la seguente procedura per controllare il formato dell'URL:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Configurazione > Ricerca e metadati > Alias URL > Pattern nel menu di amministrazione di Drupal.
  3. In Pattern per tutti i percorsi dei metodi SmartDocs specifica come vuoi generare il percorso.
  4. Seleziona Salva configurazione.

A causa della memorizzazione nella cache sul portale, potresti non vedere immediatamente le pagine del tuo modello dopo la loro pubblicazione. Se necessario, puoi svuotare manualmente la cache HTML di SmartDocs utilizzando il seguente procedura:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Configurazione > SmartDocumenti nell'amministrazione Drupal o dal menu Fogli Google.
  3. Fai clic su Ricrea le cache dei modelli SmartDocs.

Annullamento della pubblicazione di un nodo

Puoi annullare la pubblicazione di un nodo pubblicato in qualsiasi momento. L'annullamento della pubblicazione di un nodo lo rende invisibile a utenti del portale.

Per annullare la pubblicazione di un nodo:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Contenuti > SmartDocs in il menu di amministrazione di Drupal.
  3. Per il modello di cui vuoi annullare la pubblicazione, seleziona Revisioni API in Operazioni.
  4. Seleziona la revisione del modello del nodo di cui vuoi annullare la pubblicazione.
  5. Seleziona i nodi nella revisione di cui annullare la pubblicazione.
  6. Seleziona Annulla pubblicazione dei nodi dall'aggiornamento opzioni.
  7. Fai clic su Aggiorna.

Visualizzazione della revisione di un modello

Puoi creare una nuova revisione di un modello importando un nuovo file WADL o una specifica OpenAPI in un modello esistente, oppure creando manualmente una nuova revisione. Dopo aver creato la nuova revisione, puoi eseguire il rendering e pubblicare la revisione, che sostituisce i nodi Drupal attualmente pubblicati.

Puoi visualizzare e pubblicare i nodi di più revisioni contemporaneamente. In altre parole, cinque revisioni di un modello, puoi pubblicare nodi da una o da tutte le revisioni. Tuttavia, la pubblicazione un'API in un modello uguale a un nodo pubblicato di un altro modello annulla la pubblicazione del nodo precedente dell'API e la sostituisce con quella della versione più recente tramite Google Cloud CLI o tramite l'API Compute Engine.

Per vedere la revisione di un modello:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Contenuti > SmartDocumenti in il menu di amministrazione di Drupal.
  3. Per il modello da aggiornare, seleziona Revisioni API in Operazioni.
  4. Seleziona la revisione del modello che vuoi visualizzare.
  5. Esegui il rendering e pubblica i nodi come descritto sopra.

Modifica di un nodo

Dopo aver eseguito il rendering di un nodo, puoi modificarlo mediante l'editor Drupal. Ad esempio, puoi modificare il verbo HTTP e la descrizione di un'API o aggiungere una nuova query o un nuovo parametro di intestazione all'API. Tu modificare i nodi creati da un file WADL o una specifica OpenAPI, oppure i nodi che hanno creato manualmente.

Puoi anche modificare il file WADL originale o la specifica OpenAPI. Quando hai terminato modificando, importa il file WADL o la specifica OpenAPI di nuovo nel modello come nuova revisione, quindi esegui il rendering e pubblica le modifiche come descritto sopra.

Per modificare un nodo utilizzando l'editor Drupal:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Vai al nodo Drupal corrispondente alla documentazione dell'API che vuoi modifica.
  3. Seleziona Modifica per utilizzare l'editor Drupal.
  4. Una volta apportate le modifiche, seleziona Metodo di aggiornamento.

In alternativa, puoi modificare il nodo dal modello SmartDocs:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Contenuti > SmartDocumenti in il menu di amministrazione di Drupal.
  3. Per il modello da aggiornare, seleziona Revisioni API in Operazioni.
  4. Seleziona la revisione del modello da pubblicare.
  5. Seleziona Modifica metodo nel menu a discesa Operazioni per che vuoi modificare.

Per eliminare un nodo:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Contenuti > SmartDocumenti in il menu di amministrazione di Drupal.
  3. Per il modello da aggiornare, seleziona Revisioni API in Operazioni.
  4. Seleziona la revisione del modello da pubblicare.
  5. Seleziona Elimina metodo in dal menu a discesa Operazioni per il metodo.
    Attenzione:l'eliminazione del nodo rimuove anche l'API dal modello. Se vuoi annullare la pubblicazione dell'API in modo che sia nascosta agli utenti del portale, ma non vuoi eliminarla dal modello, devi annullare la pubblicazione del nodo come descritto sopra.

Il portale dispone di un report integrato che mostra informazioni su qualsiasi nodo sottoposto a rendering da un modello SmartDocumenti che non fanno più riferimento a metodi validi del modello. Accedi al report tramite selezionando Report nel menu Drupal e selezionando il report denominato stato del nodo SmartDocs.

Esportazione e importazione di un modello

SmartDocs ti consente di esportare un modello esistente in un file. Ad esempio, puoi definire un ambiente di produzione e di gestione temporanea. Poi, apporti tutte le modifiche di SmartDocs nella gestione temporanea completamente gestito di Google Cloud. Quando è tutto pronto per rilasciare le tue API, esporti il modello di gestione temporanea e lo importi nel modello di produzione.

L'importazione di un modello crea una nuova revisione del modello. SmartDocumenti cerca di trovare una corrispondenza nel modello con API importate. Se SmartDocs rileva una corrispondenza, l'importazione aggiorna il file Drupal nodo corrispondente all'API esistente. Se SmartDocs non rileva una corrispondenza, l'importazione crea un nuovo nodo Drupal per l'API.

Ad esempio, se disponi di un'API POST, corrisponde a un nodo Drupal con un ID 91. Poi importare un modello e SmartDocs rileva una corrispondenza di un'API POST nel modello importato a un API POST. Eventuali aggiornamenti all'API POST aggiornano il nodo 91 Drupal. Se SmartDocs non rileva crea un nuovo nodo Drupal con un nuovo ID.

Drupal esegue la corrispondenza utilizzando le seguenti caratteristiche dell'API:

  • internalName: il nome del modello interno.
  • httpMethod: il metodo HTTP dell'API, ad esempio GET, PUT, POST o ELIMINA.
  • resourcePath: il percorso della risorsa.
  • parametri di query: tutti i parametri di query utilizzati dall'API.

Se tutte e quattro le caratteristiche di un'API importata corrispondono a un'API esistente nel modello, SmartDocumenti aggiorna il nodo Drupal esistente.

Il modello esportato è rappresentato da un singolo oggetto JSON con voci per le risorse e di machine learning. Ciò significa che puoi modificare il modello esportato per modificare una risorsa o un metodo, quindi reimporta il modello. Se modifichi l'oggetto JSON, non modificare i seguenti campi:

  • revisionNumber
  • createdTime
  • modifiedTime
  • apiRevisionId
  • resourceId

Per esportare un modello:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Contenuti > SmartDocumenti in il menu di amministrazione di Drupal.
  3. Per il modello da esportare, seleziona Esporta in Operazioni.
  4. Seleziona il tipo di file di esportazione SmartDocs JSON.
  5. Fai clic su Esporta.
  6. Ti viene chiesto di salvare il file su disco o di aprirlo in un editor.

Per importare un modello:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Contenuti > SmartDocumenti in il menu di amministrazione di Drupal.
  3. Per il modello da importare, seleziona Importa in Operazioni.
  4. Seleziona SmartDocs JSON nel menu a discesa Scegli formato.
  5. Seleziona File o URL in il Tipo di caricamento:
      .
    1. Se selezioni File, vai al file JSON.
    2. Se selezioni URL, specifica l'URL del file JSON SmartDocs.
  6. Fai clic su Importa per importarlo nel modello.
  7. Si aprirà la pagina delle informazioni sul modello, dove potrai eseguire il rendering un modello di machine learning. Tieni presente che l'importazione crea una nuova revisione del modello.
  8. Esegui il rendering e pubblica i nodi.

Modifica del modello SmartDocs

Il modello SmartDocs definisce il modo in cui i nodi Drupal vengono visualizzati sullo schermo. Ogni SmartDocumenti può utilizzare lo stesso modello predefinito oppure personalizzarlo manualmente modello individuale.

Il modello SmartDocs include un file modello codificato come file .hbr di Handlebars, file CSS, e JavaScript. Con i manubri, gran parte dei contenuti dipende da variabili e da elementi espressioni di manubrio, come &123;&123;body}}. Un elenco delle applicazioni esistenti Le espressioni di manubrio vengono fornite in un commento nella parte superiore del file. Per informazioni su usando Handlebars per personalizzare i modelli, visita la pagina http://handlebarsjs.com.

Le seguenti sezioni descrivono come caricare un file modello SmartDocs personalizzato per l'utilizzo da parte di tutti nuovi modelli o per quando importi nuove API in un modello esistente, per sapere come ripristinare il file modello SmartDocs originale predefinito e su come modificare il modello SmartDocs per un modello individuale.

Caricare un modello personalizzato File modello SmartDocs

Puoi caricare un file modello SmartDocs personalizzato, come file .hbr di Handlebars, da utilizzare come file predefinito durante la creazione di nuovi modelli o l'importazione di nuove API in un modello esistente.

Se desideri utilizzare il file modello SmartDocs predefinito come punto di partenza durante la creazione il tuo file modello SmartDocs personalizzato, puoi scaricarne una copia da: profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr

Per caricare un file modello SmartDocs personalizzato:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Configurazione > SmartDocumenti in Drupal menu di amministrazione.
  3. Espandi l'area Impostazioni avanzate della pagina.
  4. In Carica modello di metodo personalizzato, fai clic su Scegli file e vai al file .hbr Handlebars.
  5. Fai clic su Carica.
  6. Fai clic su Salva configurazione.

Ripristino del file modello SmartDocs predefinito

Puoi ripristinare il file modello SmartDocs predefinito. Una volta ripristinato, lo stato predefinito modello verrà utilizzato quando crei nuovi modelli o importi nuove API in un modello un modello di machine learning.

Per ripristinare il file modello SmartDocs predefinito:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Configurazione > SmartDocumenti in Drupal menu di amministrazione.
  3. Espandi l'area Impostazioni avanzate della pagina.
  4. Nella sezione Carica modello di metodo personalizzato, fai clic su Rimuovi accanto al un file modello SmartDocs personalizzato.
  5. Fai clic su Salva configurazione.

In fase di modifica il modello SmartDocs per un singolo modello

Puoi modificare il modello utilizzato per un singolo modello.

Per modificare il modello per un modello individuale:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Contenuti > SmartDocs in il menu di amministrazione di Drupal.
  3. Per il modello da modificare, seleziona Impostazioni alla voce Operazioni.
  4. Nell'area Modello di metodo, modifica il modello in base alle tue esigenze.
  5. Fai clic su Salva modello.
  6. Vai a un nodo Drupal. Dovresti vedere le modifiche al modello nella pagina.

Configurare il Tipo di autenticazione SmartDocs

Le API definite in SmartDocs possono essere aperte, il che significa che non sono disponibili credenziali di autenticazione per accedervi o in modo sicuro. Un'API sicura richiede il passaggio delle credenziali quando si crea una all'API.

Per un'API sicura, SmartDocs supporta i seguenti tipi di autenticazione:

  • Autenticazione di base: passa le credenziali di autenticazione di base come coppia nome utente e password. Se non specifichi di utilizzare OAuth come tipo di credenziale, l'API per impostazione predefinita utilizza l'autenticazione di base.
  • OAuth 2.0: un fornitore di servizi di terze parti autentica la password dell'utente le credenziali, garantisce che l'utente disponga dell'autorizzazione per l'API e quindi emette un accesso di accesso. Quando effettui una richiesta SmartDocs a un'API protetta, SmartDocs crea la richiesta e la invii al fornitore di servizi. Il provider di servizi convalida quindi il token e garantisce che non sia scaduta.
  • Token personalizzato: passa un valore token come intestazione o parametro di query a ogni token richiesta.

Per ogni tipo di autenticazione, crei uno schema di sicurezza che definisce caratteristiche dell'autenticazione. Ad esempio, per l'autenticazione con token personalizzato, lo schema di sicurezza definisce la modalità di passaggio del token (intestazione, parametro di query, parametro corpo) e il nome il token.

Uno schema di sicurezza è associato a una revisione specifica di un modello. Pertanto, se crei nuova revisione di un modello, è necessario ridefinire gli schemi di sicurezza per quella revisione

In un file WADL, puoi specificare se un'API richiede l'autenticazione utilizzando il tag Apigee &lt;apigee:authentication&gt;, come come mostrato di seguito:

<method id="statusespublic_timeline" name="GET" apigee:displayName="PublicTimeline">
    ...
    <apigee:authentication required="true"/>
</method>

Se l'API è aperta, imposta l'attributo required su false.

Nota che non è possibile specificare il tipo di autenticazione nel file WADL. Per farlo devi modificando il nodo in Drupal. Per ulteriori informazioni sui file WADL, consulta la sezione WADL Riferimento.

Nella pagina dell'API in Drupal, SmartDocs aggiunge il seguente pulsante per consentire agli utenti di specificare credenziali di autenticazione di base:

Se modifichi il nodo per impostare il tipo di autenticazione su OAuth, SmartDocs aggiunge la classe pulsante seguente alla pagina:

Per il token personalizzato, SmartDocs aggiunge:

Configurazione in corso... autenticazione di base

Se utilizzi l'autenticazione di base con l'API, devi specificare solo il tag &lt;apigee:authentication&gt; nel WADL il file che utilizzi per creare il modello.

Per applicare l'autenticazione di base a metodi creati da un'origine diversa da un file WADL:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Contenuti > SmartDocs in il menu di amministrazione di Drupal.
  3. Per il modello desiderato, seleziona Revisioni API in Operazioni.
  4. Per la revisione del modello che desideri modificare, seleziona Sicurezza Impostazioni in Operazioni.
  5. Seleziona Aggiungi schema di sicurezza.
  6. Specifica il nome dello schema di sicurezza.
  7. Seleziona Base come Tipo.
  8. Seleziona Invia.
  9. Per ogni metodo nel modello, modifica il metodo per impostare il relativo schema di sicurezza allo schema di base.
    1. Seleziona Contenuti > SmartDocs in il menu di amministrazione di Drupal.
    2. Per il modello desiderato, seleziona Revisioni API in Operazioni.
    3. Seleziona Revisione per la revisione del modello da modificare. Dettagli in Operazioni.
    4. Seleziona Edit Method (Metodo di modifica) per l'API da modificare.
    5. Seleziona lo schema di sicurezza per l'API.
    6. Salva l'API.

Configurazione in corso... Autenticazione OAuth 2.0

Puoi configurare un modello in modo che utilizzi OAuth 2.0 in SmartDocs, anziché l'impostazione predefinita autenticazione. Puoi configurare OAuth in due posizioni:

  1. Crea uno schema di sicurezza per ogni revisione di un modello in Sicurezza Impostazioni per la revisione.
  2. Specifica l'ID client e il client secret per tutte le revisioni del modello in Impostazioni per il modello.
di Gemini Advanced.

Per attivare OAuth:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Contenuti > SmartDocs in il menu di amministrazione di Drupal.
  3. Per il modello che ti interessa, seleziona Revisioni API in Operazioni.
  4. Per la revisione del modello che desideri modificare, seleziona Impostazioni di sicurezza sotto Operazioni.
  5. Seleziona Aggiungi schema di sicurezza.
  6. Specifica il nome dello schema di sicurezza.
  7. Seleziona OAuth 2.0 come Tipo.
  8. Imposta il Tipo di concessione.
  9. Inserisci i valori nei campi URL di autorizzazione. L'autorizzazione Viene utilizzato l'URL per ottenere il token di accesso.
  10. Imposta il verbo di autorizzazione su GET o POST.
  11. Inserisci l'URL token di accesso. L'URL del token di accesso è l'URL utilizzato scambia il token di richiesta con un token di accesso.
  12. Inserisci il nome del parametro token di accesso.
  13. Usa In per specificare come passare il token: Header, Query o Corpo.
  14. Imposta gli Ambiti OAuth.
  15. Seleziona Invia.
  16. Seleziona Contenuti > SmartDocs in il menu di amministrazione di Drupal.
  17. Per il modello, seleziona Impostazioni nella sezione Operazioni menu a discesa.
  18. Inserisci i valori in Client ID e Cliente Secret:
  19. Seleziona Salva impostazioni di autenticazione dei modelli.
  20. Per ogni metodo nel modello, modifica il metodo per impostare il relativo schema di sicurezza al tuo schema di sicurezza OAuth.
    1. Seleziona Contenuti > SmartDocs in il menu di amministrazione di Drupal.
    2. Per il modello desiderato, seleziona Revisioni API in Operazioni.
    3. Seleziona Revisione per la revisione del modello da modificare. Dettagli in Operazioni.
    4. Seleziona Edit Method (Metodo di modifica) per l'API da modificare.
    5. Seleziona lo schema di sicurezza per l'API.
    6. Salva l'API.

Configurazione dell'autenticazione dei token personalizzati

Puoi configurare un modello per utilizzare l'autenticazione dei token personalizzati.

Per attivare i token personalizzati:

  1. Accedi al tuo portale come utente con privilegi di amministratore o di creazione di contenuti.
  2. Seleziona Contenuti > SmartDocs in il menu di amministrazione di Drupal.
  3. Per il modello desiderato, seleziona Revisioni API in Operazioni.
  4. Per la revisione del modello che desideri modificare, seleziona Sicurezza Impostazioni in Operazioni.
  5. Seleziona Aggiungi schema di sicurezza.
  6. Specifica il nome dello schema di sicurezza.
  7. Seleziona Apikey comeApikey (Tipo).
  8. Imposta il Param Name contenente il token.
  9. Usa In per specificare come passare il token: Intestazione, Query, o Corpo.
  10. Seleziona Invia.
  11. Per ogni metodo nel modello, modifica il metodo per impostare il relativo schema di sicurezza allo schema del token.
    1. Seleziona Contenuti > SmartDocs in il menu di amministrazione di Drupal.
    2. Per il modello desiderato, seleziona Revisioni API in Operazioni.
    3. Seleziona Revisione per la revisione del modello da modificare. Dettagli in Operazioni.
    4. Seleziona Edit Method (Metodo di modifica) per l'API da modificare.
    5. Seleziona lo schema di sicurezza per l'API.
    6. Salva l'API.

Eliminazione di un modello

Quando elimini un modello (Contenuti > SmartDocs, Elimina in nel campo Operations in Drupal), il modello viene eliminato dall'organizzazione Edge. Ciò significa che altri portali fanno riferimento al modello, il modello non è più disponibile. Per ulteriori informazioni, consulta Informazioni su modelli e modelli SmartDoc.