Utilizzo di SmartDocumenti per documentare le API

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. informazioni

SmartDocumenti consente di documentare le API sul portale per gli sviluppatori di Drupal 7 in modo da rendere la documentazione delle API completamente interattiva. Grazie alla documentazione interattiva, gli utenti del portale possono:

  • Informazioni sulle API
  • Inviare una richiesta in tempo reale all'API
  • Visualizza 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 facilmente le tue API.

L'API di gestione perimetrale è un'API RESTful che consente di accedere ai servizi API utilizzando qualsiasi client HTTP. Apigee utilizza SmartDoc per creare documentazione interattiva per l'API Edge Management. Consulta la documentazione dell'API qui.

Esempio di portale SmartDocumenti

Per utilizzare SmartDocumenti, devi disporre di un portale Apigee Developer Services. Per maggiori informazioni, consulta la pagina relativa alla creazione di un portale per gli sviluppatori.

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

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

L'API Hello World è stata creata dalla specifica OpenAPI di destinazione fittizia, mocktarget.yaml. Per saperne di più, consulta 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. Lo SmartDocumenti per questa risorsa viene 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 sulla scheda cURL per visualizzare la chiamata cURL corrispondente.

Come documentare le API con SmartDocs

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

I passaggi generali da seguire per utilizzare SmartDocumenti sono:

  1. Configura il modulo Drupal SmartDocs sul portale.
  2. Crea un modello SmartDocumenti.
  3. Aggiungi API al modello da un file WADL, dalla specifica 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 della tua API supporta sia una richiesta POST che una richiesta PUT, SmartDocs crea un nodo Drupal separato per POST e PUT.
  5. Pubblica i nodi Drupal. Una volta pubblicata, gli utenti del portale possono visualizzare e interagire con l'API.
  6. Modifica i nodi Drupal prima o dopo la pubblicazione. Puoi modificare i nodi Drupal utilizzando l'editor Drupal o modificando il file WADL originale o la specifica OpenAPI. Quando hai finito di modificare il file WADL o la specifica OpenAPI, importalo di nuovo nel modello come nuova revisione, quindi esegui il rendering e pubblica le modifiche.
  7. Abilita TLS. Poiché SmartDocumenti può inviare credenziali di autenticazione al tuo backend nell'ambito di una richiesta alle tue API, dovresti abilitare TLS sul tuo 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 iniziare a utilizzare il portale, devi ottenere il tuo certificato TLS e abilitare TLS. Per saperne di più, consulta la pagina relativa all'utilizzo di TLS sul portale.

Informazioni sui modelli e sui modelli SmartDoc

Quando crei un modello nel portale, questo viene effettivamente archiviato nell'organizzazione Edge, non in Drupal. Un modello è un grande blocco di JSON con 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 inviati al modello di origine.

Archiviati nell'organizzazione

Archiviati in Drupal

ottimizzabili

templates

Nodi Drupal con funzionalità di modifica

Supponi di avere più portali nella tua organizzazione (ad esempio sviluppo, fase e produzione). In Pantheon, sposti un portale da un ambiente all'altro. Sembra che ogni istanza del portale contenga il proprio modello, ma in realtà tutti fanno riferimento al modello di origine. 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 produzione.

I modelli controllano l'aspetto e il design dei tuoi SmartDocumenti, che vengono archiviati in ogni istanza del portale, Pertanto, in teoria, ogni portale può utilizzare un modello unico per ogni modello. Tuttavia, una delle comodità del framework di rendering è che a ciascun modello viene applicato automaticamente un modello predefinito (quello di Apigee o un modello fornito da te).

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 nella tua organizzazione:

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

Configurazione del modulo SmartDocumenti

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

Per configurare il modulo SmartDocumenti:

  1. Accedi al portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Modules (Moduli) nel menu di amministrazione di Drupal. Viene visualizzato l'elenco di tutti i moduli Drupal installati.
  3. Attiva il modulo SmartDocs.
  4. Salva la configurazione.
  5. Seleziona Moduli nel menu Amministratore di Drupal.
  6. Seleziona SmartDocuments -> Autorizzazioni e assicurati che l'opzione "Esegui attività di amministrazione per il modulo SmartDocumenti" per il ruolo di "Amministratore" sia attiva.
  7. Seleziona Configurazione > Portale di sviluppo nel menu di amministrazione di Drupal.
  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 Lunghezza massima dei componenti su 255.
    3. Espandi Punteggiatura.
    4. Per le impostazioni delle opzioni Parentesi graffa aperta ({) e Parentesi graffa destra (}), seleziona Nessuna azione (non sostituire).
    5. Fai clic su Salva configurazione.
  11. Se il tuo portale per sviluppatori sarà 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'URL del proxy dell'API SmartDocs come segue:
    1. Seleziona Configuration > SmartDocuments nel menu Amministrazione di Drupal.
    2. Espandi Impostazioni avanzate.
    3. Aggiorna il campo URL del proxy di 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

      Per impostazione predefinita, 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 della tua API. Puoi definire più modelli sul portale per supportare API diverse o raggruppare tutte le tue API in un singolo modello.

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

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

dove:

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

Ad esempio, se specifichi il nome interno come "mymodel", l'URL per il nodo Drupal generato 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, viene archiviato nell'organizzazione Edge come origine della struttura API. Per saperne di più, consulta Informazioni sui modelli e sui modelli SmartDoc.

  1. Accedi al portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Contenuti > Smart Docs nel menu di amministrazione di Drupal.
  3. Seleziona Nuovo modello nella parte superiore della pagina.
  4. Compila i seguenti campi:
    • Nome: il nome del modello che verrà visualizzato sul sito.
    • Nome interno: man mano che digiti il Nome, viene visualizzato il nome interno. 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.

Una volta creato il modello, verrai reindirizzato alla relativa pagina. Da qui, puoi utilizzare il menu a discesa Operazioni bx per:

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

Aggiunta di API a un modello

Per aggiungere API a un modello:

  • 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 SmartDocumenti in un modello. In genere, questo file viene creato esportando un modello esistente, modificando il file e quindi importando gli aggiornamenti. Per saperne di più, consulta la sezione "Esportazione e importazione di un modello" di seguito.

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

Importare un WADL

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

  1. Accedi al portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Content > SmartDocs nel menu di amministrazione di Drupal.
  3. Seleziona il modello che vuoi aggiornare.
  4. In Operazioni, seleziona Importa.
  5. Seleziona WADL nel menu a discesa Scegli formato nella pagina di importazione di SmartDocumenti.
  6. Seleziona File o URL nel menu a discesa Tipo di caricamento.
    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. Viene visualizzata la pagina delle informazioni sul modello, dove puoi ora eseguire il rendering del modello.

Importa una specifica OpenAPI

Dopo aver creato correttamente un modello, puoi importare una specifica OpenAPI (in precedenza Swagger). Edge supporta OpenAPI versione 1.2 e 2.0.

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

Per importare una specifica OpenAPI:

  1. Accedi al portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Contenuti > SmartDocs nel menu di amministrazione di Drupal.
  3. Seleziona il modello che vuoi aggiornare.
  4. In Operazioni, seleziona Importa.
  5. Seleziona JSON Swagger o Swagger YAML nel menu a discesa Choose Format nella pagina di importazione di SmartDocs.
  6. Seleziona File o URL nel menu a discesa Tipo di caricamento (devi selezionare URL per OpenAPI 1.2).
    1. Se selezioni File, vai alla specifica OpenAPI.
    2. Se selezioni URL, specifica l'URL della specifica OpenAPI.
  7. Fai clic su Importa per importarlo nel modello.
  8. Viene visualizzata la pagina delle informazioni sul modello, dove puoi ora eseguire il rendering del modello.

Crea manualmente risorse e metodi

Se non disponi di un file WADL o di una specifica OpenAPI che rappresenti 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, dopo l'importazione.

Per aggiungere manualmente un'API:

  1. Crea una nuova revisione del modello.

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

    https://myCompany.com/v1

    Quando aggiungi risorse al modello, queste 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 richiamato su una risorsa. Ad esempio, per la risorsa "/login", supporti POST per l'accesso e DELETE per la disconnessione. Questa risorsa non supporta altri verbi HTTP, come PUT o GET. Pertanto, definisci 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 URL sono definiti in un'unica risorsa in SmartDocumenti.

Come regola generale:

  • Crea un modello SmartDoc diverso per ogni percorso di base univoco nell'API.
  • Definisci una risorsa SmartDocs diversa per ogni risorsa univoca nell'API.
  • Definisci un metodo SmartDoc 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à una revisione, puoi aggiungere la tua risorsa. Se il modello è nuovo e non ha revisioni, crea una nuova revisione.

Per creare una nuova revisione di un modello:

  1. Accedi al portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Contenuti > SmartDocuments nel menu di amministrazione di Drupal.
  3. Per il modello che vuoi aggiornare, seleziona Aggiungi revisione in Operazioni.
  4. Nella pagina Aggiungi revisione API, inserisci le seguenti informazioni:
    • Nome visualizzato: il nome della revisione così come viene visualizzato nel portale.
    • ID versione: un breve identificatore per la revisione.
    • Descrizione: una descrizione della revisione.
    • URL di base: l'URL di base di tutte le API nella revisione del modello. Un modello può utilizzare URL di base diversi per ogni revisione. Ad esempio, includi un indicatore di 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. Verrai reindirizzato alla 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, devi specificare il percorso della risorsa, che viene combinato con l'URL di base nella revisione del modello per creare l'URL completo della risorsa.

Per definire una risorsa:

  1. Accedi al portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Contenuti > SmartDocumenti nel menu di amministrazione di Drupal.
  3. Per il modello che vuoi aggiornare, in Operazioni, seleziona Revisioni API 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 Aggiungi risorsa, inserisci le informazioni seguenti:
    • Nome visualizzato: il nome della risorsa.
    • Percorso: il percorso della risorsa, che inizia con "/". Il valore di 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: facoltativamente, inserisci l'oggetto JSON che definisce ciascun parametro nella risorsa. Questi parametri sono descritti di seguito.
  7. Seleziona Aggiungi risorsa. Ti reindirizzeremo alla pagina del modello. Ora puoi definire i metodi nella risorsa.

Facoltativamente, puoi aggiungere parametri alla risorsa, ad esempio parametri di modello, query e intestazione. Tutti i parametri della risorsa vengono ereditati da qualsiasi metodo definito al suo interno. Pertanto, se definisci un parametro di query sulla risorsa, tutti i metodi aggiunti alla risorsa devono supportare questo parametro di query.

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

L'immagine seguente mostra una pagina SmartDocumenti esistente per l'API Apigee Approva or Revoca App Developer, con ogni tipo di parametro evidenziato:

Ogni tipo di parametro è definito da un oggetto JSON:

Tipo

Oggetto JSON

Note

Modello

{
"dataType": "string",
"defaultValue": "",
"description": "Il nome dell'organizzazione.",
"name": "org_name",
"required": true,
"type": "TEMPLATE"
}

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

Il valore description viene visualizzato in una finestra popup quando l'utente passa il mouse sopra l'URL in una pagina SmartDocumenti.

Query

{
"dataType": "string",
"defaultValue": "",
"description": "La località.",
"name": "w",
"required": true,
"type": "QUERY"
}

I parametri di query obbligatori possono comunque specificare un valore defaultValue, ma spesso non lo sono.

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

Titolo

{
"dataType": "string",
"defaultValue": "application/json",
"description": "Specifica come <code>application/json</code>.",
"name": "Content-Type",
"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 parametri modello sulla risorsa. Osserva come ogni definizione di parametro nell'array di parametri è separata 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, racchiusa 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 le parti org_name e developer_email dell'URL prima di poter inviare una richiesta.

Definizione di un metodo

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

Durante la definizione del metodo, specifica tutti i parametri utilizzati dal metodo, inclusi i parametri di query e di intestazione. Per informazioni sull'aggiunta di parametri a un metodo, consulta la descrizione riportata sopra per le risorse.

L'immagine seguente mostra una pagina SmartDocumenti esistente per l'API Apigee Create Developer con ogni area della pagina evidenziata con il valore corrispondente che hai impostato durante la definizione di un metodo:

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

Per definire un metodo:

  1. Accedi al portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Contenuti > SmartDocuments nel menu di amministrazione di Drupal.
  3. Per il modello che vuoi aggiornare, in Operazioni, seleziona Revisioni API 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 una delle risorse.
  6. Nella pagina Edit Method (Modifica metodo), inserisci le seguenti informazioni:
    • Display Name: il nome dell'API, che diventa anche il titolo della 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 metodo. Per ulteriori informazioni, vedi Configurare il tipo di autenticazione SmartDocumenti.
    • Tipo di contenuti: il tipo di contenuti della richiesta e della risposta. Consulta la sezione riportata di seguito sulla configurazione di diversi metodi di autenticazione.
    • Parametri: (facoltativo) qualsiasi parametro di query o di intestazione per il metodo. Per saperne di più, consulta la descrizione riportata sopra per l'aggiunta di un parametro a una risorsa.
    • (Facoltativo) Documentazione del corpo della richiesta: descrivi il corpo della richiesta. I metodi POST e PUT accettano il corpo di una richiesta. Puoi utilizzare quest'area per descriverla. Se ometti questo valore, il link Descrizione in Corpo della richiesta viene omesso dalla pagina SmartDocumenti generata.
    • Esempio di corpo della richiesta: (facoltativo) mostra un esempio del corpo di una richiesta, generalmente sotto forma di oggetto JSON o XML. Per i verbi POST e PUT, l'Esempio di corpo della richiesta viene passato come parte di ogni richiesta. Gli utenti della pagina SmartDocumenti modificano questo esempio prima di inviare una richiesta all'API. Se ometti questo valore, il link Valore in Corpo della richiesta viene omesso dalla pagina SmartDocumenti generata.
    • Tag: array di tag associati all'API. SmartDocumenti utilizza i tag per raggruppare API simili. Ad esempio, puoi applicare il tag "Statistiche" a tutte le API relative alle statistiche. Puoi raggruppare le API di risorse diverse in un singolo tag, se utilizzano tutte lo stesso tag.
  7. Seleziona Add Method (Aggiungi metodo). Ti reindirizzeremo alla pagina del modello. Ora puoi eseguire il rendering e pubblicare il tuo metodo.

Rendering di un modello

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

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

Per eseguire il rendering di un modello:

  1. Accedi al portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Contenuti > SmartDocuments" nel menu di amministrazione di Drupal.
  3. Per il modello di cui vuoi 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 per il rendering.
  6. Seleziona Esegui il rendering dei nodi dal menu a discesa Opzioni di aggiornamento.
  7. Fai clic su Aggiorna.
  8. Viene visualizzata una schermata di caricamento che mostra l'avanzamento del rendering dei nodi.
    Una volta eseguito il rendering dei nodi, l'ID del nodo Drupal per ogni API viene visualizzato nella colonna Node Association (Associazione nodo) del modello. Fai clic sul link nella colonna Associazione del nodo per vedere il nodo sottoposto a rendering.

Anziché selezionare Esegui il rendering dei nodi,puoi selezionare Esegui il rendering e pubblica i 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. Facoltativamente, puoi scegliere di pubblicare i 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 portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Contenuti > SmartDocs nel menu di amministrazione di Drupal.
  3. Per il modello che vuoi 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 dal menu a discesa Opzioni di aggiornamento.
  8. Fai clic su Aggiorna.
  9. Accedi al nodo selezionando l'ID nodo nella colonna Associazione nodo.

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

  1. Accedi al portale come utente con privilegi di amministratore o per la 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 SmartDocumenti, specifica come vuoi generare il percorso.
  4. Seleziona Salva configurazione.

A causa della memorizzazione nella cache sul portale, potresti non visualizzare le pagine del tuo modello immediatamente dopo la loro pubblicazione. Se necessario, puoi svuotare manualmente la cache HTML di Smart Docs seguendo questa procedura:

  1. Accedi al portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Configurazione > Smart Docs nel menu di amministrazione di Drupal.
  3. Fai clic su Ricrea le cache dei modelli di SmartDocumenti.

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 agli utenti del portale.

Per annullare la pubblicazione di un nodo:

  1. Accedi al portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Contenuti > SmartDocuments" nel 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 per i quali annullare la pubblicazione.
  6. Seleziona Annulla pubblicazione dei nodi dal menu a discesa Aggiorna 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 la specifica OpenAPI in un modello esistente oppure creando manualmente una nuova revisione. Dopo aver creato la nuova revisione, puoi eseguire il rendering e la pubblicazione della revisione, che sostituisce i nodi Drupal attualmente pubblicati.

Puoi eseguire il rendering e la pubblicazione dei nodi di più revisioni contemporaneamente. Ciò significa che se hai cinque revisioni di un modello, puoi pubblicare i nodi di una o tutte le revisioni. Tuttavia, la pubblicazione di un'API in un modello uguale a un nodo pubblicato di un altro modello annulla la pubblicazione della versione precedente dell'API e la sostituisce con quella dell'API pubblicata più di recente.

Per vedere la revisione di un modello:

  1. Accedi al portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Contenuti > SmartDocs" nel menu di amministrazione di Drupal.
  3. Per il modello che desideri 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 utilizzando 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. Puoi modificare i nodi creati da un file WADL o una specifica OpenAPI oppure i nodi creati manualmente.

Puoi anche modificare il file WADL originale o la specifica OpenAPI. Al termine delle modifiche, importa di nuovo il file WADL o la specifica OpenAPI 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 portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Naviga fino al nodo Drupal corrispondente alla documentazione dell'API che vuoi modificare.
  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 SmartDocumenti:

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

Per eliminare un nodo:

  1. Accedi al portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Contenuti > SmartDocs nel menu di amministrazione di Drupal.
  3. Per il modello che desideri aggiornare, seleziona Revisioni API in Operazioni.
  4. Seleziona la revisione del modello da pubblicare.
  5. Seleziona Elimina metodo nel menu a discesa Operazioni per il metodo.
    Attenzione: l'eliminazione del nodo rimuove anche l'API dal modello. Se vuoi solo 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 in precedenza.

Il portale dispone di un report integrato che mostra informazioni su qualsiasi nodo visualizzato da un modello SmartDocumenti che non fanno più riferimento a un metodo valido del modello. Accedi al report selezionando Report nel menu Drupal, quindi seleziona il report denominato Stato nodo SmartDocumenti.

Esportazione e importazione di un modello

SmartDocumenti consente di esportare un modello esistente in un file. Ad esempio, puoi definire un ambiente di produzione e uno temporaneo. Successivamente, apporti tutte le modifiche di Smart Docs nell'ambiente di gestione temporanea. Quando è tutto pronto per rilasciare le API, puoi esportare il modello temporaneo e importarlo nel modello di produzione.

Quando importi un modello, viene creata una nuova revisione del modello. SmartDocumenti cerca di abbinare le API esistenti nel modello alle API importate. Se SmartDocumenti rileva una corrispondenza, l'importazione aggiorna il nodo Drupal corrispondente all'API esistente. Se SmartDocumenti non rileva una corrispondenza, l'importazione crea un nuovo nodo Drupal per l'API.

Ad esempio, se hai un'API POST corrispondente a un nodo Drupal con ID 91, Successivamente, importi un modello e SmartDocumenti rileva una corrispondenza di un'API POST nel modello importato con l'API POST esistente. Eventuali aggiornamenti all'API POST aggiornano quindi il nodo 91 di Drupal. Se SmartDocumenti non rileva una corrispondenza, 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 DELETE.
  • resourcePath: il percorso della risorsa.
  • parametri 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, SmartDocs aggiorna il nodo Drupal esistente.

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

  • revisionNumber
  • createdTime
  • modifiedTime
  • apiRevisionId
  • resourceId

Per esportare un modello:

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

Per importare un modello:

  1. Accedi al portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Contenuti > Smart Docs" nel menu di amministrazione di Drupal.
  3. Per il modello che vuoi importare, seleziona Importa in Operazioni.
  4. Seleziona JSON SmartDocuments nel menu a discesa Scegli formato.
  5. Seleziona File o URL nella sezione Tipo di caricamento:
    1. Se selezioni File, vai al file JSON.
    2. Se selezioni URL, specifica l'URL del file JSON SmartDocumenti.
  6. Fai clic su Importa per importarlo nel modello.
  7. Viene visualizzata la pagina delle informazioni sul modello, dove puoi ora eseguire il rendering del modello. Tieni presente che l'importazione crea una nuova revisione del modello.
  8. Esegui il rendering e pubblica i nodi.

Modifica del modello Smart Docs

Il modello SmartDocumenti definisce il modo in cui i nodi Drupal vengono visualizzati sullo schermo. Ogni modello SmartDocumenti può utilizzare lo stesso modello predefinito oppure è possibile personalizzare manualmente il modello utilizzato per un singolo modello.

Il modello SmartDocumenti include un file modello codificato come file .hbr di Handlebars, file CSS e file JavaScript. Con i manubri, gran parte dei contenuti è guidata da variabili tramite l'utilizzo di espressioni incorporate nei comandi manubri, ad esempio &123;&123;body}}. Un elenco delle espressioni manubrio esistenti viene fornito in un commento nella parte superiore del file. Per informazioni sull'utilizzo dei manubri per personalizzare i tuoi modelli, visita la pagina http://handlebarsjs.com.

Le seguenti sezioni descrivono come caricare un file di modello SmartDocumenti personalizzato per l'utilizzo da parte di tutti i nuovi modelli o per l'importazione di nuove API in un modello esistente, come ripristinare il file del modello SmartDocumenti originale originale e come modificare il modello SmartDocumenti per un singolo modello.

Caricamento di un file di modello SmartDocumenti personalizzato

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

Se vuoi utilizzare il file modello Smart Docs predefinito come punto di partenza per la creazione del tuo file modello SmartDocumenti personalizzato, puoi scaricare una copia da: profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr

Per caricare un file modello SmartDocumenti personalizzato:

  1. Accedi al portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Configurazione > Smart Docs nel menu di amministrazione di Drupal.
  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 SmartDocumenti predefinito

Puoi ripristinare il file del modello SmartDocumenti predefinito. Una volta ripristinato, il file del modello SmartDocumenti predefinito verrà utilizzato durante la creazione di nuovi modelli o l'importazione di nuove API in un modello esistente.

Per ripristinare il file modello SmartDocumenti predefinito:

  1. Accedi al portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Configurazione > Smart Docs nel menu di amministrazione di Drupal.
  3. Espandi l'area Impostazioni avanzate della pagina.
  4. In Carica modello di metodo personalizzato, fai clic su Rimuovi accanto al file del modello SmartDocumenti personalizzato.
  5. Fai clic su Salva configurazione.

Modifica del modello SmartDocumenti per un singolo modello

Puoi modificare il modello utilizzato per un singolo modello.

Per modificare il modello per un singolo modello:

  1. Accedi al portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Contenuti > SmartDocs" nel menu di amministrazione di Drupal.
  3. Per il modello che vuoi modificare, seleziona Impostazioni in Operazioni.
  4. Nell'area Modello del metodo, modifica il modello come richiesto.
  5. Fai clic su Salva modello.
  6. Naviga fino a un nodo Drupal. Dovresti visualizzare le modifiche apportate al modello nella pagina.

Configurazione del tipo di autenticazione SmartDocumenti

Le API definite in SmartDocumenti possono essere aperte, il che significa che non sono necessarie credenziali di autenticazione per accedervi, oppure essere sicure. Un'API sicura richiede il trasferimento delle credenziali quando viene effettuata una chiamata 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 di nome utente e password. Se non specifichi di utilizzare OAuth come tipo di credenziale, l'API utilizza per impostazione predefinita l'autenticazione di base.
  • OAuth 2.0: un fornitore di servizi di terze parti autentica le credenziali dell'utente, si assicura che l'utente disponga dell'autorizzazione per l'API e quindi emette un token di accesso. Quando effettui una richiesta SmartDocumenti a un'API protetta, SmartDoc crea la richiesta e la invia al fornitore di servizi. Il fornitore di servizi convalida quindi il token e si assicura che non sia scaduto.
  • Token personalizzato: passa un valore del token sotto forma di intestazione o parametro di ricerca a ogni richiesta.

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

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

In un file WADL, specifichi se un'API richiede l'autenticazione utilizzando il tag Apigee <apigee:authentication>, 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.

Tieni presente che non è possibile specificare il tipo di autenticazione nel file WADL. Per farlo, modifica il nodo in Drupal. Per maggiori informazioni sui file WADL, consulta la documentazione di riferimento WaDL.

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

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

Per il token personalizzato, SmartDocumenti aggiunge:

Configurazione dell'autenticazione di base

Se utilizzi l'autenticazione di base con la tua API, devi solo specificare il tag <apigee:authentication> nel file WADL 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 portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Contenuti > SmartDocs nel menu di amministrazione di Drupal".
  3. Per il modello desiderato, seleziona Revisioni API in Operazioni.
  4. Per la revisione del modello che vuoi modificare, seleziona Impostazioni di sicurezza in Operazioni.
  5. Seleziona Aggiungi schema di sicurezza.
  6. Specifica il nome dello schema di sicurezza.
  7. Seleziona Di base come Tipo.
  8. Seleziona Invia.
  9. Per ogni metodo nel modello, modificalo per impostare lo schema di sicurezza sullo schema di base.
    1. Seleziona Contenuti > SmartDocs nel menu di amministrazione di Drupal".
    2. Per il modello desiderato, seleziona Revisioni API in Operazioni.
    3. Per la revisione del modello che vuoi modificare, seleziona Dettagli revisione in Operazioni.
    4. Seleziona Edit Method (Metodo di modifica) per l'API che vuoi modificare.
    5. Seleziona lo schema di sicurezza per l'API.
    6. Salva l'API.

Configurazione dell'autenticazione OAuth 2.0

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

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

Per attivare OAuth:

  1. Accedi al portale come utente con privilegi di amministratore o per la creazione di contenuti.
  2. Seleziona Contenuti > SmartDocs nel menu di amministrazione di Drupal".
  3. In corrispondenza del modello che ti interessa, seleziona Revisioni API in Operazioni.
  4. Per la revisione del modello che vuoi modificare, seleziona Impostazioni di sicurezza in 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'URL di autorizzazione viene utilizzato 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 per scambiare il token di richiesta con un token di accesso.
  12. Inserisci il Nome del parametro token di accesso.
  13. Utilizza In per specificare come trasmettere il token: Intestazione, Query o Corpo.
  14. Imposta gli ambiti OAuth.
  15. Seleziona Invia.
  16. Seleziona Contenuti > SmartDocs nel menu di amministrazione di Drupal".
  17. Per il modello, seleziona Impostazioni nel menu a discesa Operazioni.
  18. Inserisci i valori in ID client e Client secret.
  19. Seleziona Salva impostazioni di autenticazione modello.
  20. Per ogni metodo nel modello, modifica il metodo in modo da impostare lo schema di sicurezza sullo schema di sicurezza OAuth.
    1. Seleziona Contenuti > SmartDocs nel menu di amministrazione di Drupal".
    2. Per il modello desiderato, seleziona Revisioni API in Operazioni.
    3. Per la revisione del modello che vuoi modificare, seleziona Dettagli revisione in Operazioni.
    4. Seleziona Edit Method (Metodo di modifica) per l'API che vuoi 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 token personalizzata.

Per abilitare i token personalizzati:

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

Eliminazione di un modello

Quando elimini un modello (Content > SmartDocs, Delete nel campo Operazioni in Drupal), il modello viene eliminato dall'organizzazione Edge. Ciò significa che se altri portali fanno riferimento al modello, quest'ultimo non è più disponibile. Per maggiori informazioni, consulta Informazioni sui modelli e sui modelli SmartDoc.