Generazione della documentazione API REST con OpenAPI

È possibile generare la documentazione dell'API REST utilizzando la openapi-3.0 funzionalità, che supporta la specifica OpenAPI. Documenta le tue API REST, specifica le API pubbliche e private, scegli di abilitare la scansione delle annotazioni e distribuisci le tue applicazioni web su un server Liberty. Quindi, è possibile visualizzare la documentazione API generata da openapi-3.0 in un browser che utilizza un'interfaccia utente intuitiva.

Funzionalità stabilizzate: Le funzionalità OpenAPI V3, openapi-3.0 e openapi-3.1, sono state stabilizzate. È possibile continuare a utilizzare le funzionalità. Tuttavia, l'alternativa strategica è quella di utilizzare una funzione MicroProfile OpenAPI come mpOpenAPI-3.0.

Per ulteriori informazioni sull'utilizzo di MicroProfile OpenAPI con Liberty, consultare il sito web Open Liberty.

Prima di iniziare

Scopri le specifiche dell' OpenAPIV3. Utilizzi file YAML o JSON per documentare le API RESTful nelle tue applicazioni.

È possibile utilizzare le interfacce Java e i modelli di programmazione disponibili nella specifica OpenAPI dell' MicroProfile, versione 1.0. La mpOpenAPI-1.0 funzione implementa la specifica MicroProfile OpenAPI. Per ulteriori informazioni sulle funzionalità mpOpenAPI-1.0 e successive, consultare Generazione della documentazione API REST con MicroProfileOpenAPI.

Informazioni su questa attività

È possibile esplorare queste funzionalità, quali la nuova interfaccia utente, le annotazioni e le interfacce di programmazione, con le seguenti applicazioni di esempio.

Prova a documentare un'applicazione RESTful utilizzando le annotazioni OpenAPI nel codice Java™ con l'applicazione di esempio delle annotazioni OpenAPI V3.
Vedi un esempio di documento OpenAPI V3 in formato YAML creato con un editor di testo con OpenAPI V3 documento di esempio.
Estendere la openapi-3.0 funzionalità utilizzando le io.swagger.oas.integration.OpenAPIConfigurationBuilder interfacce di programmazione con l 'esempio di interfaccia di programmazione OpenAPIConfiguration.

Procedura

Crea la documentazione dell' OpenAPI.
È possibile documentare e creare un OpenAPIs e in diversi modi:
- Specificare le annotazioni dell' OpenAPI e nel codice Java per potenziare e documentare un'applicazione.
- Utilizza un editor di testo per documentare l'API con tag OpenAPI, quindi inserisci il file completato openapi.json openapi.yaml, openapi.yml, o nella META-INF directory della tua applicazione.
- Utilizza le io.swagger.oas.integration.OpenAPIConfigurationBuilder interfacce di programmazione per creare il modello OpenAPI dall'interno dell'applicazione. Questa interfaccia e le altre interfacce di programmazione correlate per OpenAPI V3 sono disponibili nei file JAR nella /wlp/dev/api/third-party directory. Affinché la openapi-3.0 funzione avvii l' OpenAPIConfigurationBuilder,, l'archivio dell'applicazione deve contenere un META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder file. Il contenuto di questo file è il nome completo dell' OpenAPIConfigurationBuilder (Risoluzione dei conflitti di proprietà).
  Per ulteriori informazioni sulle interfacce di programmazione disponibili, sulle descrizioni delle loro funzionalità e sugli esempi di utilizzo, consultare OpenAPI Interfacce di programmazione V3.
Abilita la openapi-3.0 funzione nella configurazione del server Liberty.
1. Aggiungi la openapi-3.0 funzione al gestore delle funzioni.
```
<server>
   <featureManager>
      <feature>openapi-3.0</feature>
   </featureManager>
</server>
```
2. Facoltativo: specificare che un'applicazione OpenAPI è privata.
  
  Per impostazione predefinita, la documentazione di OpenAPI è pubblica. Tutti gli utenti possono accedere alle API pubbliche, spesso senza autenticazione. Le API pubbliche sono documentate nella /api/docs risorsa.
  È possibile specificare che le API rimangano private. Le API per uso amministrativo sono generalmente riservate. Le API private, che utilizzano password per la protezione, sono documentate nella /ibm/api/docs risorsa. Questa risorsa documenta tutte le API private e tutte le API pubbliche.
  
  È possibile specificare API private per le applicazioni web in due modi:
  - Utilizzare webModuleDoc nella configurazione del server, con public l'attributo impostato su false.
    1. Aggiungi un openapi elemento e imposta il suo enablePrivateURL attributo booleano su true.
    2. Aggiungi un webModuleDoc sottoelemento per ogni applicazione web e imposta il suo public attributo booleano su true per le API pubbliche e su false per le API private.
    L'esempio seguente rende visibile l'applicazione delle compagnie aeree OpenAPIs e disabilita l'esposizione dell'applicazione airlinesAdmin OpenAPIs.
```
<openapi enablePrivateURL="true">
  <webModuleDoc contextRoot="/airlines" public="true" />
  <webModuleDoc contextRoot="/airlinesAdmin" public="false" />
</openapi>
```
    Per impostazione predefinita, public l'attributo di webModuleDoc è impostato su true. Questa configurazione è necessaria solo per disabilitare le applicazioni che desideri mantenere private.
  - Utilizza una parola chiave di estensione del fornitore nella descrizione dell'API per indicare che un'API è privata.
    1. Aggiungi un openapi elemento alla configurazione del server e imposta il suo enablePrivateURL attributo booleano su true.
    2. Inserisci la x-ibm-private: true parola chiave e il valore nel file del META-INF/openapi.yaml documento di descrizione dell'API o in un file di un altro formato supportato. Questo valore sovrascrive la visibilità predefinita dell'API e può essere sovrascritto da una webModuleDoc voce.
3. Opzionale: specificare che un'applicazione non venga visualizzata nel documento " OpenAPI ".
  
  Per impostazione predefinita, i moduli web che contengono documenti API REST vengono visualizzati nel documento unificato " OpenAPI " disponibile nella /api/docs risorsa. Per impedire la visualizzazione dei moduli Web nel documento OpenAPI, modificare gli attributi webModuleDoc dell'elemento nella configurazione del server.
  Identifica il modulo web che desideri nascondere o visualizzare con contextRoot l'attributo. Quindi, modifica enabled l'attributo in false per nascondere il modulo web dal documento OpenAPI. Il valore predefinito per enabled l'attributo è true. Nell'esempio seguente, il modulo delle compagnie aeree è configurato in modo da apparire nel documento OpenAPI, mentre il modulo airlinesAdmin è nascosto.
```
<openapi>
  <webModuleDoc contextRoot="/airlines" enabled="true" />
  <webModuleDoc contextRoot="/airlinesAdmin" enabled="false" />
</openapi>
```
  Nota: enabled l'attributo non è supportato per i documenti API REST forniti da altre funzionalità Liberty.
Opzionale: abilita la scansione delle annotazioni JAX-RS.

Aggiungi la jaxrs-2.0 funzione al gestore delle funzioni. Quando entrambe le funzionalità jaxrs-2.0 openapi-3.0 e sono abilitate in un server, lo scanner delle annotazioni esegue la scansione di tutte le applicazioni web distribuite sul server, a meno che la configurazione del server non disabiliti la scansione. Lo scanner esamina le classi annotate con l'annotazione OpenAPI 3.0 nella definizione della classe e con l'annotazione @Path JAX-RS. È possibile accedere ai documenti generati dall' OpenAPI e tramite l'endpoint pubblico OpenAPI (api/docs) e l'endpoint privato (ibm/api/docs).
Consenti la visibilità delle API di terze parti per applicazioni specifiche.
Per abilitare il caricamento in fase di esecuzione delle annotazioni, del modello e dei modelli di programmazione dell' OpenAPI, è necessario abilitare la visibilità delle API di terze parti per l'applicazione specifica.
1. Definire apiTypeVisibility l'attributo classloader dell'elemento come visibilità API di terze parti. Aggiungi third-party all'elemento classloader nel tuo server.xml file.
  
  Se non si specifica classloader da includere third-party in apiTypeVisibility, viene utilizzata la definizione predefinita di spec, stable, e ibm-api.
```
<application id="scholar" name="Scholar" type="ear" location="scholar.ear">
  <classloader apiTypeVisibility="spec, ibm-api, stable, third-party" commonLibraryRef="Alexandria" />
</application>
```
Opzionale: abilita la convalida dei documenti OpenAPI.

La funzionalità di convalida è disabilitata per impostazione predefinita. Quando si abilita la convalida, ogni documento OpenAPI fornito dall'applicazione viene convalidato in base ai vincoli dichiarati nella specifica OpenAPIV3 dalla openapi-3.0 funzione. Se openapi-3.0 trova un documento OpenAPI non valido, la funzione segnala un errore nei log per ogni vincolo violato. Il documento non valido viene escluso dal documento aggregato OpenAPI restituito api/docs dall'endpoint. Per abilitare la convalida, impostare validation l'attributo su true nel server.xml file.
```
<openapi validation="true"/>
```
Distribuisci le tue applicazioni.
Visualizza il documento API generato in un browser.
È possibile trovare il documento API generato /api/docs all'endpoint utilizzando uno dei seguenti URL, a seconda che l'API sia pubblica o privata.
- Per le API pubbliche non SSL, consulta il documento all'indirizzo http://Liberty_host:http_port/api/docs.
- Per le API pubbliche di SSL, consulta la documentazione all'indirizzo https://Liberty_host:https_port/api/docs.
- Per le API private di SSL, consulta il documento all'indirizzo https://Liberty_host:https_port/ibm/api/docs.
Suggerimento: per impostazione predefinita, sono disponibili due endpoint per un server.
- GET http://Liberty_host:http_port/api/docs
- GET http://Liberty_host:http_port/api/explorer
È possibile personalizzare gli URL per gli endpoint pubblici con publicURL l'attributo nel server.xml file. L'esempio seguente illustra la configurazione nel server.xml file per rendere disponibile la documentazione pubblica dell'API REST con GET http://Liberty_host:http_port/myAPI/docs and http://Liberty_host:http_port/myAPI/explorer.
```
<openapi publicURL="myAPI" />
```
Il documento " OpenAPI " viene generato e aggregato tra le applicazioni per quel server Liberty. Il documento è in formato YAML per impostazione predefinita. Quando visualizzi la documentazione con Microsoft Internet Explorer 11, viene restituito un documento YAML non formattato correttamente. Come soluzione alternativa, utilizzare un browser come Mozilla Firefox o Google Chrome. Se la http richiesta ha Accept un'intestazione con un application/json valore, il documento è in formato JSON.

Suggerimento: è possibile filtrare il documento OpenAPI in base alla radice del contesto. Sia l'endpoint pubblico (api/docs) che quello privato (ibm/api/docs) supportano un parametro di query, root, che può filtrare i contesti radice trovati. Ad esempio, una chiamata a GET http://Liberty_host:http_port/api/docs?root=/myApp recupera un documento OpenAPI V3 che contiene solo la documentazione relativa alla myApp radice del contesto.

Risultati

L'interfaccia utente dell' OpenAPI rende le definizioni aggregate da /api/docs per visualizzare un'interfaccia utente intuitiva su http://Liberty_host:http_port/api/explorer. Se abiliti SSL, puoi accedere all'interfaccia utente protetta all'indirizzo https://Liberty_host:https_port/api/explorer.

È possibile sfogliare i moduli web privati abilitando enablePrivateURL l'attributo openAPI nell'elemento del server.xml file.

<openapi enablePrivateURL="true"/>

Quando la navigazione nel modulo web privato è abilitata, utilizzare https://Liberty_host:https_port/ibm/api/explorer per visualizzare l'interfaccia utente intuitiva sia per i moduli web pubblici che per quelli privati.

In questa interfaccia utente è possibile visualizzare tutti gli endpoint RESTful dalla propria applicazione. È inoltre possibile filtrare gli endpoint visualizzati per concentrarsi su applicazioni specifiche.