[17.0.0.1 and later]

Remplacement de certains champs des documents Swagger 2.0

Utilisez un attribut swaggerDefinition dans un fichier server.xml pour remplacer certains champs dans les documents Swagger 2.0 fournis par les noeuds finaux /docs et /explorer.

Avant de commencer

Vous devez d'abord ajouter la fonction apiDiscovery-1.0 à votre fichier server.xml, puis exposer la documentation Swagger 2.0 dans des points d'extrémité REST Liberty. Effectuez les étapes 1 et 2 de la procédure décrite dans Découverte de la documentation d'API REST sur un serveur Liberty.

Procédure

  1. Créez un fragment Swagger au format JSON ou YAML, contenant les champs à remplacer. Les champs dont les valeurs peuvent être remplacées sont info, schemes, consumes, produces et externalDocs.

    Par exemple, le fragment swaggerDefinition suivant change description, title et les autres zones info dans les pages HTML /explorer.

    {  
      "swagger":"2.0",
      "info":{  
         "description":"My description",
         "version":"1.0.0",
         "title":"My title",
         "x-ibm-css":"${server.config.dir}/css/acme-banner.css",
         "termsOfService":"http://swagger.io/terms/",
         "contact":{  
            "email":"apiteam@swagger.io"
         },
         "license":{  
            "name":"Apache 2.0",
            "url":"http://www.apache.org/licenses/LICENSE-2.0.html"
         }
      }
    }

    En plus des champs title et description, vous pouvez personnaliser les éléments de bannière et de logo dans les pages HTML /explorer. A l'intérieur de la zone info du fragment swaggerDefinition, vous pouvez spécifier une zone x-ibm-css pointant sur un emplacement d'un fichier CSS qui remplace la portion de la bannière et du logo. Le format du fichier CSS doit respecter les règles suivantes :

    • Le fichier CSS doit contenir un élément CSS .swagger-section #header.
    • Un nouveau logo doit être spécifié au format images/logo-perso.png, où logo-perso représente le nom du fichier image. Veillez à ce que le chemin du fichier soit spécifié relativement à l'emplacement du fichier CSS.
    • Le fichier CSS doit désigner le fichier image du logo personnalisé avec la propriété background-image. La valeur de cette propriété doit être de la forme url(images/logo-perso.png).
    • Le fichier du logo doit être au format PNG.

    Voici un exemple de fichier CSS de remplacement :

    .swagger-section #header {
      background-image: url(images/custom-logo.png);
      background-repeat: no-repeat;
      background-color: lightslategray;
      background-position-x: 28px;
      padding-top: 20px;
      padding-right: 0px;
      padding-bottom: 20px;
      padding-left: 5px;
      height: 75px;
    }
  2. Ajoutez un attribut swaggerDefinition à votre fichier server.xml.

    La valeur de l'attribut swaggerDefinition peut être l'une des suivantes :

    • Chemin d'un fichier local portant l'extension .json ou .yaml. Ce chemin d'accès peut inclure des variables Liberty associées à des répertoires d'exécution, par exemple :
      <apiDiscovery swaggerDefinition="${server.config.dir}/custom/swaggerDef.yaml" />
    • URL absolue d'un fragment Swagger commençant par http ou par https, par exemple :
      <apiDiscovery swaggerDefinition="http://mycompany.com/api/swaggerDef.json" />
    • Racine de contexte d'une application déployée sur le serveur. La racine de contexte commence avec une barre oblique (/), par exemple :
      <apiDiscovery swaggerDefinition="/myApplication" />

    Lorsqu'une seule application web est déployée sur un serveur Liberty, pour améliorer l'expérience utilisateur, le document Swagger de cette application est utilisé comme fragment swaggerDefinition. Même si aucun attribut swaggerDefinition n'est défini dans le fichier server.xml, tous les champs de l'application sont remplacés dans un document Swagger fourni par les points d'extrémité /docs. Lorsqu'une deuxième application web est déployée sur le serveur, tous les champs dont les valeurs ont été remplacées par l'optimisation du déploiement à une seule application retrouvent leurs valeurs par défaut.


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

Nom du fichier : twlp_api_discovery_swagger_def.html