Generazione della documentazione API REST con OpenAPI

Puoi generare la tua documentazione API REST utilizzando la funzione openapi-3.0 , che supporta la specifica OpenAPI . Documentare le API REST, specificare le API pubbliche e private, scegliere di abilitare la scansione delle annotazioni e distribuire le applicazioni web su un server Liberty . Poi, è possibile visualizzare la documentazione API generata da openapi-3.0 in un browser che utilizza un'interfaccia utente user - friendly.

Funzioni stabilizzate Le funzioni OpenAPI V3 , openapi-3.0 e openapi-3.1, sono stabilizzate. È possibile continuare ad utilizzare le funzioni. Tuttavia, l'alternativa strategica è utilizzare una funzione MicroProfile OpenAPI come mpOpenAPI-3.0.

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

Prima di iniziare

Informazioni sulla specificaOpenAPI V3. Si utilizzano i file YAML o JSON per documentare le API RESTful nelle applicazioni.

Puoi utilizzare le interfacce Java e i modelli di programmazione disponibili da MicroProfile OpenAPI Specification versione 1.0. La funzione mpOpenAPI-1.0 implementa la specifica MicroProfile OpenAPI . Per ulteriori informazioni sulle funzioni mpOpenAPI-1.0 e successive, vedi Generating REST API documentation with MicroProfile OpenAPI.

Informazioni su questa attività

È possibile esplorare queste funzioni, come 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™ utilizzando l'applicazione di esempio di annotazione OpenAPI V3.
Vedi un esempio di un documento OpenAPI V3 in formato YAML creato con un editor di testo con OpenAPI V3.
Estendere la funzione openapi-3.0 utilizzando le interfacce di programmazione io.swagger.oas.integration.OpenAPIConfigurationBuilder con l' esempio di interfaccia di programmazioneOpenAPIConfiguration.

Procedura

Crea la documentazione OpenAPI .
Puoi documentare e creare OpenAPIs in diversi modi:
- Specificare le annotazioni OpenAPI nel codice Java per convertire e documentare un'applicazione.
- Utilizzare un editor di testo per documentare l'API con le tag OpenAPI e quindi inserire il file openapi.yaml, openapi.ymlo openapi.json completato nella directory META-INF della tua applicazione.
- Utilizza le interfacce di programmazione io.swagger.oas.integration.OpenAPIConfigurationBuilder per creare il modello OpenAPI dall'applicazione. Questa interfaccia, e le altre interfacce di programmazione correlate per OpenAPI V3, sono disponibili nei file JAR nella directory /wlp/dev/api/third-party . Affinché la funzione openapi-3.0 avvii la funzione OpenAPIConfigurationBuilder,, l'archivio dell'applicazione deve avere un file META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder. Il contenuto di questo file è il nome completamente qualificato del sito OpenAPIConfigurationBuilder.
  Per ulteriori informazioni sulle interfacce di programmazione disponibili, descrizioni delle loro funzionalità ed esempi del loro utilizzo, vedi OpenAPI V3 programming interfaces.
Abilita la funzione openapi-3.0 nella configurazione del server Liberty .
1. Aggiungere la funzione openapi-3.0 al gestore funzioni.
```
<server>
   <featureManager>
      <feature>openapi-3.0</feature>
   </featureManager>
</server>
```
2. Facoltativo: specificare che l'applicazione OpenAPI è privata.
  
  Per impostazione predefinita, la documentazione OpenAPI è pubblica. Tutti gli utenti possono accedere alle API pubbliche, spesso senza autenticazione. Le API pubbliche sono documentate nella risorsa /api/docs .
  È possibile specificare che le API restano private. Le API per uso amministrativo sono tipicamente tenute private. Le API private, che utilizzano le password per la protezione, sono documentate nella risorsa /ibm/api/docs . Questa risorsa documenta tutte le API private e tutte le API pubbliche.
  
  È possibile specificare API private per applicazioni web in due modi:
  - Utilizzare webModuleDoc nella configurazione del server, con l'attributo public impostato su false.
    1. Aggiungere un elemento openapi e impostare il suo attributo enablePrivateURL Boolean a true.
    2. Aggiungere un elemento secondario webModuleDoc per ogni applicazione web e imposta il proprio attributo public Boolean a true per le API pubbliche e a false per le API private.
    Il seguente esempio 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, l'attributo public di webModuleDoc è impostato su true. Questa configurazione è necessaria solo per disabilitare le applicazioni che si desidera mantenere private.
  - Utilizzare una parola chiave di estensione del fornitore nella descrizione API per designare che un'API è privata.
    1. Aggiungere un elemento openapi alla configurazione del server e impostare il suo attributo enablePrivateURL Boolean a true.
    2. Inserire la parola chiave e il valore x-ibm-private: true nel file del documento di descrizione API META-INF/openapi.yaml o nel file di un altro formato supportato. Questo valore sovrascrive la visibilità predefinita dell'API e questo valore può essere sovrascritto da una voce webModuleDoc .
3. Facoltativo: specificare che un'applicazione non viene visualizzata nel documento OpenAPI .
  
  Per impostazione predefinita, i moduli web che contengono i documenti API REST vengono visualizzati nel documento OpenAPI unito disponibile nella risorsa /api/docs . Per evitare che i moduli Web vengano visualizzati nel documento OpenAPI , modificare gli attributi dell'elemento webModuleDoc nella configurazione del server.
  Identificare il modulo web che si desidera nascondere o visualizzare con l'attributo contextRoot . Modificare quindi l'attributo enabled in false per nascondere il modulo web dal documento OpenAPI . Il valore predefinito per l'attributo enabled è true. Nel seguente esempio, il modulo delle linee aeree è configurato in modo che venga visualizzato nel documento OpenAPI mentre il modulo airlinesAdmin è nascosto.
```
<openapi>
  <webModuleDoc contextRoot="/airlines" enabled="true" />
  <webModuleDoc contextRoot="/airlinesAdmin" enabled="false" />
</openapi>
```
  Nota: L'attributo enabled non è supportato per i documenti API REST forniti da altre funzioni Liberty .
Opzionale: Abilita scansione annotazione JAX - RS.

Aggiungere la funzione jaxrs-2.0 al gestore funzioni. Quando sia le funzioni jaxrs-2.0 che openapi-3.0 sono abilitate in un server, lo scanner di annotazione scandisce tutte le applicazioni web distribuite sul server a meno che la configurazione del server non disabilita la scansione. Lo scanner passa attraverso le classi annotate con le annotazioni OpenAPI 3.0 nella definizione della classe e annotate con l'annotazione JAX - RS @Path . Puoi accedere ai documenti OpenAPI generati con l'endpoint pubblico OpenAPI (api/docs) e l'endpoint privato (ibm/api/docs).
Consenti visibilità API di terze parti per applicazioni specifiche.
Per abilitare il caricamento di runtime delle annotazioni, del modello e dei modelli di programmazione OpenAPI , devi abilitare la visibilità API di terzi per l'applicazione specifica.
1. Definire l'attributo apiTypeVisibility dell'elemento classloader come visibilità API di terze parti. Aggiungere third-party all'elemento classloader nel proprio file server.xml .
  
  Se non si specifica classloader per includere third-party in apiTypeVisibility, utilizza la definizione predefinita di spec, stablee ibm-api.
```
<application id="scholar" name="Scholar" type="ear" location="scholar.ear">
  <classloader apiTypeVisibility="spec, ibm-api, stable, third-party" commonLibraryRef="Alexandria" />
</application>
```
Facoltativo: Abilita la convalida dei documenti OpenAPI .

La capacità di convalida è disabilitata per impostazione predefinita. Quando abiliti la convalida, ogni documento OpenAPI fornito dall'applicazione viene convalidato rispetto ai vincoli dichiarati nella specifica OpenAPI V3 dalla funzione openapi-3.0 . Se openapi-3.0 trova un documento OpenAPI che non è valido, la funzione riporta un errore nei log per ogni vincolo violato. Il documento non valido viene escluso dal documento aggregato OpenAPI restituito dall'endpoint api/docs . Per abilitare la convalida, impostare l'attributo validation su true nel file server.xml .
```
<openapi validation="true"/>
```
Distribuire le applicazioni.
Visualizza il documento API generato in un browser.
Puoi individuare il tuo documento API generato nell'endpoint /api/docs utilizzando uno dei seguenti URL, a seconda che la tua API sia pubblica o privata.
- Per le API pubbliche non SSL, visualizza il tuo documento all' http://Liberty_host:http_port/api/docs.
- Per le API pubbliche SSL, visualizza il tuo documento all'indirizzo https://Liberty_host:https_port/api/docs.
- Per le API private SSL, visualizza il tuo documento all' https://Liberty_host:https_port/ibm/api/docs.
Suggerimento: Per impostazione predefinita, due endpoint sono disponibili per un server.
- GET http://Liberty_host:http_port/api/docs
- GET http://Liberty_host:http_port/api/explorer
È possibile modificare gli URL per gli endpoint pubblici con l'attributo publicURL nel file server.xml . Il seguente esempio illustra la configurazione nel file server.xml per rendere la documentazione dell'API REST pubblica disponibile 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 tale server Liberty . Il documento è in formato YAML per impostazione predefinita. Quando si visualizza la documentazione con Microsoft Internet Explorer 11, viene restituito un documento YAML non formattato correttamente. Come soluzione temporanea, utilizza un browser come il browser Mozilla Firefox o Google Chrome . Se la richiesta http ha un'intestazione Accept con un valore application/json , il documento è in formato JSON.

Suggerimento : puoi filtrare il documento OpenAPI in base alla root di contesto. Sia l'endpoint pubblico (api/docs) che l'endpoint privato (ibm/api/docs) supportano un parametro query, root, che può filtrare le root di contesto trovate. Ad esempio, una chiamata a GET http://Liberty_host:http_port/api/docs?root=/myApp richiama un documento OpenAPI V3 che ha solo la documentazione per la root contesto myApp .

Risultati

L'interfaccia utente OpenAPI esegue il rendering delle definizioni aggregate da /api/docs per visualizzare un'interfaccia utente di facile utilizzo all'indirizzo http://Liberty_host:http_port/api/explorer. Se si abilita SSL, è possibile accedere all'interfaccia utente protetta all'indirizzo https://Liberty_host:https_port/api/explorer.

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

<openapi enablePrivateURL="true"/>

Quando è abilitata l'esplorazione del modulo web privato, utilizzare https://Liberty_host:https_port/ibm/api/explorer per visualizzare la UI umana per i moduli web pubblici e privati.

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