Personnalisation de la documentation OpenAPI

Vous pouvez personnaliser certains aspects du document OpenAPI principal disponible sur le noeud final /api/docs et de l'interface utilisateur OpenAPI disponible sous /api/explorer avec des éléments tels que l'élément externalDocs et l'élément info. Liberty surveille les modifications apportées aux fichiers de personnalisation dans les emplacements de chemin par défaut pour traiter et mettre à jour les modifications apportées au document OpenAPI principal et à l'interface utilisateur.

Fonctions stabilisées: les fonctions OpenAPI V3 , openapi-3.0 et openapi-3.1, sont stabilisées. Vous pouvez continuer de les utiliser. Toutefois, l'alternative stratégique consiste à utiliser une fonction MicroProfile OpenAPI telle que mpOpenAPI-3.0.

Avant de commencer

Pour savoir comment générer et activer la documentation OpenAPI , voir Génération de la documentation de l'API REST avec OpenAPI.

Générez de la documentation et affichez un exemple d'interface utilisateur personnalisable à l'aide de l' exemple d'application de compagnies aériennes OpenAPI V3.

Procédure

Définissez une personnalisation dans un fragment OpenAPI.
Créez un fragment suivant la structure de la spécification OpenAPI 3.0.0. Le fragment peut être dans un fichier YAML ou JSON ou disponible à une URL.
L'élément info fournit un titre, une description et d'autres informations. Vous pouvez personnaliser les valeurs du titre et de la description. Vous pouvez également personnaliser la barre d'en-tête pour éditer le logo, la zone de filtre et le bouton de filtre. A l'intérieur du champ info du fragment de personnalisation, utilisez un champ x-ibm-css faisant référence à l'emplacement d'un fichier CSS définissant un style pour les éléments HTML dans la barre d'en-tête.
Le fragment n'a pas besoin d'être complet par lui-même. L'exemple de fragment suivant personnalise l'élément info qui fait référence à un CSS qui définit un style pour la barre d'en-tête de l'interface utilisateur 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
```
Le fichier CSS peut être un fichier local ou disponible à une URL donnée. Le chemin peut inclure des variables Liberty qui sont associées à des répertoires d'exécution.
Ce fichier CSS possède les exigences de format suivantes pour être considéré valide.
- Le fichier CSS spécifie au moins un élément qui commence par .swagger-ui .headerbar.
- Seuls les contenus spécifiés sous les éléments CSS qui commencent par .swagger-ui .headerbar sont utilisés.
- Le fichier de logo personnalisé qui est référencé par le fichier CSS doit être au format PNG.
- Un fichier de logo personnalisé doit être appelé custom-logo.png et placé sous images/custom-logo.png.
- Le chemin d'accès du fichier de logo doit être relatif au fichier CSS.
- Le fichier CSS doit faire référence au logo avec la propriété background-image définie sur la valeur url(images/custom-logo.png).
L'exemple de fragment suivant montre un fichier CSS de remplacement.
```
.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;
}
```
Configurez la surveillance des fichiers pour vos fichiers de personnalisation.

Vous pouvez sauvegarder votre fichier de personnalisation dans l'emplacement par défaut pour la surveillance automatique ou bien modifier la configuration du serveur afin de définir un emplacement pour votre fichier. Si plusieurs fichiers de personnalisation par défaut sont spécifiés, un message d'avertissement s'affiche dans la console, indiquant le fichier de personnalisation supervisé et les fichiers ignorés. Le fichier de personnalisation sélectionné pour la surveillance est surveillé en continu par Liberty jusqu'à ce qu'il soit supprimé.

Remarque: seuls les fichiers de personnalisation sont surveillés pour les mises à jour. Les fichiers CSS et les fichiers de logo ne sont pas surveillés. Les URL ne sont pas surveillées.
1. Sauvegardez le fragment de personnalisation dans le type de fichier YAML, YML ou JSON dans ${server.config.dir}/openapi/customization.file_type pour utiliser la surveillance de fichier de personnalisation par défaut.
2. Facultatif: Ajoutez un élément openapi avec un attribut customization qui référence le fragment dans le fichier de configuration du serveur Liberty .
  
  Les emplacements des définitions de personnalisation par défaut ne sont pas surveillés lorsque l'attribut customization est défini de manière explicite. L'attribut customization peut spécifier un fichier YAML, YML ou JSON, qui est surveillé par Liberty. Le chemin peut inclure des variables Liberty associées à des répertoires d'exécution, comme dans l'exemple suivant.
```
<openapi customization="${server.config.dir}/custom/customInfo.yaml" />
```
  L'attribut customization peut également spécifier une URL qui renvoie un fragment OpenAPI.
```
<openapi customization="http://myWebsite.com/myCustomOpenAPI" />
```
Facultatif: Désactivez la surveillance des fichiers pour les fichiers de personnalisation.

Liberty surveille en continu les fichiers de personnalisation par défaut. Cependant, la surveillance des fichier utilise des ressources systèmes additionnelles. Si vous n'avez pas de fichier de personnalisation ou si vos fichiers de personnalisation sont statiques et ne changent pas, il est recommandé de désactiver la surveillance des fichiers.

Dans votre fichier de configuration du serveur, définissez l'attribut booléen disableFileMonitor sur true pour l'élément openapi. Les emplacements des définitions de personnalisation par défaut sont également surveillés lorsque l'attribut disableFileMonitor est défini sur true.
```
<openapi disableFileMonitor="true" />
```