[17.0.0.3 and later]

Personnalisation de la documentation OpenAPI

Vous pouvez personnaliser certains aspects du document OpenAPI maître 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 supervise les modifications apportées aux fichiers de personnalisation aux emplacements d'accès par défaut pour traiter et mettre à jour les modifications dans le document OpenAPI maître et dans l'interface utilisateur.

Avant de commencer

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

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

Procédure

  1. 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 adresse 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 de la zone info du fragment de personnalisation, utilisez une zone 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 adresse URL donnée. Le chemin d'accès peut inclure des variables Liberty 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 commençant avec .swagger-ui .headerbar.
    • Seuls les contenus spécifiés sous les éléments CSS commençant 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;
    }
  2. 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 qui est sélectionné pour la surveillance est surveillé continuellement par Liberty jusqu'à sa suppression.

    Remarque : Seuls les fichiers de personnalisation font l'objet d'une surveillance 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 un fichier de type YAML, YML ou JSON sous ${server.config.dir}/openapi/customization.type_fichier pour utiliser la surveillance du fichier de personnalisation par défaut.
    2. Facultatif : Ajoutez un élément openapi avec un attribut customization faisant référence au fragment contenu 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 surveillé par Liberty. Le chemin d'accès peut inclure des variables Liberty associées à des répertoires d'exécution, comme dans l'exemple ci-dessous.

      <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" />
  3. Facultatif : Désactivez la surveillance de fichier pour les fichiers de personnalisation.

    Liberty surveille continuellement 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" />

Icône indiquant le type de rubrique Rubrique Tâche

Nom du fichier : twlp_api_openapi_custom.html