Personnalisation de l'interface utilisateur OpenAPI

Vous pouvez personnaliser des aspects de l'interface utilisateur OpenAPI disponible sur les noeuds finaux /openapi/ui et /api/explorer. Liberty surveille les modifications apportées aux fichiers CSS de personnalisation pour traiter et mettre à jour les modifications apportées à l'interface utilisateur OpenAPI .

Avant de commencer

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

Procédure

  1. Personnalisez le fichier CSS afin d'éditer le style des éléments HTML de la barre d'en-tête de l'interface utilisateur OpenAPI.
    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).

    Le fragment suivant illustre la substitution d'un fichier CSS :

    .swagger-ui .headerbar {
   background-color: #5f3345;
}
 .swagger-ui .headerbar .headerbar-wrapper {
   background-image: url(images/custom-logo.png);
}
  2. Configurez la surveillance des fichiers pour votre fichier CSS de personnalisation.

    Vous pouvez enregistrer votre fichier CSS personnalisé sous les emplacements $server.config.dir/mpopenapi/customization.css et $server.config.dir/openapi-3.1/customization.css pour sa surveillance automatique. L'emplacement du premier fichier CSS s'applique au noeud final /openapi/ui.  L'emplacement du second fichier CSS s'applique au noeud final /api/explorer. Si vous désirez également spécifier un logo personnalisé, enregistrez-le sous les emplacements $server.config.dir/mpopenapi/images/custom-logo.png et $server.config.dir/openapi-3.1/images/custom-logo.png et référencez-le dans le fichier CSS aux deux emplacements.

    Remarque: seuls les fichiers CSS sont surveillés pour les mises à jour. Les fichiers logo ne sont pas surveillés. Une modification d'un des fichiers logo doit être suivie d'une mise à jour de son fichier CSS correspondant pour être détectée dynamiquement.
  3. Facultatif: Surveillance des fichiers de contrôle pour les fichiers de personnalisation.

    Liberty surveille en continu les fichiers de personnalisation CSS par défaut. Toutefois, la surveillance de ces fichiers consomme des ressources système supplémentaires. Vous pouvez modifier la fréquence à laquelle des mises à jour sont recherchées pour les fichiers surveillés. Si vous ne disposez pas d'un fichier de personnalisation, il est recommandé de désactiver la surveillance des fichiers.

    La propriété de configuration mp.openapi.extensions.liberty.file.polling.interval spécifique la fréquence à laquelle les mises à jour sont recherchées dans les fichiers surveillés. La valeur de cette propriété est un entier non négatif. L'intervalle est exprimé en secondes. La valeur par défaut est de 2 secondes. Définir la valeur sur 0 désactive la surveillance des fichiers.
    La configuration est injectée par la spécification MicroProfile Config.
    Remarque: La valeur de cette propriété est vérifiée uniquement lorsque les fonctions mpOpenAPI-1.0 ou openapi-3.1 sont activées.