Personalizzazione della documentazione OpenAPI

È possibile personalizzare gli aspetti del documento principale OpenAPI disponibile nell'endpoint /api/docs e nell'interfaccia utente OpenAPI all'indirizzo /api/explorer con elementi quali l'elemento externalDocs e l'elemento info . Liberty monitora le modifiche ai file di personalizzazione nelle ubicazioni del percorso predefinito per elaborare e aggiornare le modifiche al documento e all'interfaccia utente OpenAPI principale.

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.

Prima di iniziare

Per informazioni su come creare e abilitare la documentazione OpenAPI , vedi Generating REST API documentation with OpenAPI.

Genera una documentazione ed esegui il rendering di un esempio di IU personalizzabile utilizzando l'applicazione Sample OpenAPI V3 Airlines.

Procedura

Definire una personalizzazione in un frammento OpenAPI .
Crea un frammento che segue la struttura della specifica OpenAPI 3.0.0 . Lo snippet può essere contenuto in un file YAML o JSON o disponibile all'indirizzo URL.
L'elemento info fornisce titolo, descrizione e altre informazioni. È possibile personalizzare i valori di titolo e descrizione. È inoltre possibile personalizzare la barra dell'intestazione per modificare il logo, la casella del filtro e il pulsante del filtro. Nel campo info del frammento di personalizzazione, utilizzare un campo x-ibm-css per puntare all'ubicazione di un file CSS che stili gli elementi HTML nella barra di intestazione.
Il frammento non deve essere completato da solo. Il seguente frammento di esempio personalizza l'elemento info , che punta a un CSS che definisce lo stile della barra di intestazione dell'IU OpenAPI .
```
---
openapi: 3.0.0
info:
  title: Airlines APIs
  description: Book flights and manage reservations
  version: 2.1.0
  x-ibm-css: ${server.config.dir}/openapi/header.css
```
Il CSS può essere un file locale o disponibile all'indirizzo URL. Il percorso può includere variabili Liberty associate alle directory di runtime.
Questo file CSS ha i seguenti requisiti di formato per essere considerato valido.
- Il file CSS specifica almeno un elemento che inizia con .swagger-ui .headerbar.
- Vengono utilizzati solo i contenuti specificati in elementi CSS che iniziano con .swagger-ui .headerbar .
- Il file logo personalizzato a cui fa riferimento il file CSS deve essere in formato PNG.
- Un file di logo personalizzato deve essere denominato custom-logo.png e collocato in images/custom-logo.png.
- Il percorso del file logo deve essere relativo al file CSS.
- Il file CSS deve fare riferimento all'immagine del logo con la proprietà background-image impostata sul valore url(images/custom-logo.png) .
Il seguente frammento di esempio mostra un file CSS di sovrascrittura.
```
.swagger-ui .headerbar {
   background-color: #5f3345;
}
 .swagger-ui .headerbar .headerbar-wrapper {
   background-image: url(images/custom-logo.png);
}
 .swagger-ui .headerbar .filter-wrapper .filter-button {
    background: rgba(252, 48, 81, 0.53);
   color: #e8e8e8;
}
 .swagger-ui .headerbar .filter-wrapper input[type=text] {
        border: 1px solid #ebebeb;
}
```
Configurare il controllo file per i propri file di personalizzazione.

È possibile salvare il file di personalizzazione nell'ubicazione predefinita per il monitoraggio automatico oppure è possibile modificare la configurazione del server per definire un'ubicazione per il file. Se viene specificato più di un file di personalizzazione predefinito, viene visualizzato un messaggio di avvertenza nella console che indica il file di personalizzazione monitorato e i file ignorati. Il file di personalizzazione selezionato per il monitoraggio viene monitorato continuamente da Liberty fino a quando non viene eliminato.

Nota: solo i file di personalizzazione vengono monitorati per gli aggiornamenti. I file CSS e logo non sono monitorati. Gli URL non vengono monitorati.
1. Salva il frammento di personalizzazione nel tipo di file YAML, YML o JSON in ${server.config.dir}/openapi/customization.file_type per utilizzare il monitoraggio del file di personalizzazione predefinito.
2. Facoltativo: Aggiungere un elemento openapi con un attributo customization che fa riferimento al frammento nel file di configurazione del server Liberty .
  
  Le posizioni delle definizioni di personalizzazione predefinite non vengono monitorate quando l'attributo customization è impostato esplicitamente. L'attributo customization può specificare un file YAML, YML o JSON, monitorato da Liberty. Il percorso può includere variabili Liberty associate alle directory di runtime, come nel seguente esempio.
```
<openapi customization="${server.config.dir}/custom/customInfo.yaml" />
```
  L'attributo customization può anche specificare un URL che restituisce un frammento OpenAPI.
```
<openapi customization="http://myWebsite.com/myCustomOpenAPI" />
```
Facoltativo: Disabilitare il controllo file per i file di personalizzazione.

Liberty monitora continuamente i file di personalizzazione per impostazione predefinita. Tuttavia, il monitoraggio dei file utilizza ulteriori risorse di sistema. Se non si dispone di alcun file di personalizzazione o se i file di personalizzazione sono statici e non vengono modificati, è utile disattivare il monitoraggio dei file.

Nel file di configurazione del server, impostare l'attributo booleano disableFileMonitor su true per l'elemento openapi . Le ubicazioni delle definizioni di personalizzazione predefinite non sono monitorate quando l'attributo disableFileMonitor viene impostato su true.
```
<openapi disableFileMonitor="true" />
```