Découverte de la documentation d'API REST sur un serveur Liberty

La fonction de découverte des API (API Discovery) vous permet de trouver la documentation de vos API REST sur un serveur Liberty et d'identifier les API REST disponibles. Utilisez l'interface utilisateur Swagger pour démarrer les points d'extrémité REST disponibles.
[18.0.0.1 and later]Conseil : Vous pouvez utiliser la fonction openapi-3.0 pour découvrir la documentation de vos API REST. La fonction openapi-3.0 peut être catégorisée comme la version suivante de la fonction apiDiscovery-1.0. Vous pouvez mettre à jour un document Swagger V2 créé avec apiDiscovery-1.0 vers OpenAPI V3. Voir Génération d'une documentation d'API REST avec OpenAPI.

Procédure

  1. Ajoutez la fonction apiDiscovery-1.0 à un gestionnaire de fonctions dans le fichier server.xml du serveur Liberty dont vous souhaitez découvrir les API REST disponibles.

    La fonction apiDiscovery-1.0 active les bundles de découverte d'API REST dans le produit. La fonction affiche également la documentation issue des points d'extrémité REST Liberty tels que JMX, si la configuration du serveur utilise la fonction restConnector-1.0, et des collectivités si la configuration du serveur utilise la fonction collectiveController-1.0.

    Assurez-vous que la configuration du serveur comporte toutes les fonctions nécessaires à votre application déployée, par exemple jaxrs-2.0. Modifiez les ports pour que le serveur puisse ouvrir ses ports HTTP.

    Si vous souhaitez afficher la documentation d'API REST privée, configurez une entrée d'objet keyStore et une entrée de registre d'utilisateurs dans le fichier server.xml.

    [17.0.0.1 and later]En revanche, si vous souhaitez uniquement afficher la documentation publique, vous n'avez besoin d'ajouter ces entrées (objet keyStore et registre d'utilisateurs) que si l'accès à la documentation doit se faire à travers HTTPS. L'accès à la documentation publique via HTTP ne nécessite pas d'entrée d'objet keyStore ni d'entrée de registre d'utilisateurs.

    Le fichier server.xml suivant comporte la fonction apiDiscovery-1.0 :

    <server>
        <featureManager>
            <feature>apiDiscovery-1.0</feature>
        </featureManager>
    
        <httpEndpoint id="defaultHttpEndpoint"
                      host="*"
                      httpPort="8010"
                      httpsPort="8020"/>
    
        <keyStore id="defaultKeyStore" password="Liberty"/>
      
        <basicRegistry id="basic" realm="ibm/api">
            <user name="bob" password="bobpwd" />
        </basicRegistry>
    </server>
  2. Affichez la documentation Swagger 2.0 dans les points d'extrémité REST Liberty.

    Si l'application Web contient deux instances ou plus de la classe javax.ws.rs.core.Application pour fonctionner correctement avec la fonction de découverte des API, chaque application nécessite une valeur javax.ws.rs.@ApplicationPath unique ou la définition d'un mappage d'URL (url-mapping) dans le fichier web.xml.

    Activez la fonction apiDiscovery-1.0 pour faire fusionner la documentation en cours avec la documentation trouvée lors de l'analyse des annotations. Le produit recherche un fichier META-INF/stub/swagger.json ou META-INF/stub/swagger.yaml dans le module Web. Si la fonction trouve l'un de ces fichiers, elle génère un document Swagger contenant à la fois le contenu du fichier et toute annotation JAX-RS et Swagger contenue dans le module Web. Vous pouvez utiliser cette fonction pour documenter des servlets non JAS-RS car la documentation est fusionnée automatiquement avec les parties JAX-RS.Vous pouvez configurer l'emplacement de votre documentation d'API de deux façons :

    • Utilisez la méthode getDocument de l'interface SPI com.ibm.wsspi.rest.api.discovery.APIProvider.

      La méthode getDocument permet aux bundles OSGi des fonctions d'extension d'apporter les documents des API REST à la documentation maître globale. Pour cette édition, les seuls types de document pris en charge sont DocType.Swagger_20_JSON et DocType.Swagger_20_YAML. Les implémenteurs de cette interface peuvent renvoyer le document JSON ou YAML sérialisé en tant que valeur de java.lang.String, ou bien ils peuvent transmettre une référence de fichier (préfixée avec file:///) à l'emplacement de fichier JSON ou YAML.

    • Utilisez une application Web déployée.

      Chaque module Web peut fournir son propre document d'API REST. Plusieurs fichiers WAR à l'intérieur d'un fichier d'application d'entreprise (EAR) peuvent avoir des documents Swagger 2.0 différents.

      La façon la plus simple d'afficher la documentation de modules Web consiste à inclure un fichier swagger.json ou swagger.yaml dans le dossier META-INF correspondant. Durant le déploiement d'application, la fonction de découverte des API recherche une valeur META-INF/swagger.json pour chacun des modules Web. Si une valeur META-INF/swagger.json est introuvable, la fonction recherche une valeur META‐INF/swagger.yaml.

      Une autre façon d'afficher la documentation d'API REST pour un module Web consiste à modifier un fichier de configuration server.xml. Placez un élément webModuleDoc pour chaque module web dans un élément apiDiscovery parent. Par exemple :

      <apiDiscovery>
         <webModuleDoc contextRoot="/30ExampleServletInEar" enabled="true" docURL="/swagger.json" />	
         <webModuleDoc contextRoot="/22ExampleServlet" enabled="false" />
         <webModuleDoc contextRoot="/custom" enabled="true" docURL="http://petstore.swagger.io/v2/swagger.json" />
      </apiDiscovery>

      L'élément webModuleDoc doit avoir l'attribut contextRoot afin d'identifier de manière unique le module Web dont vous souhaitez afficher la documentation.

      Un attribut facultatif, enabled, fait basculer la découverte d'API d'un module Web. La valeur par défaut de cet attribut est true.

      L'attribut docURL spécifie où rechercher la documentation d'un module Web. La valeur de docURL peut commencer par une barre oblique (/) afin que l'URL soit relative à la racine de contexte. Par exemple, /30ExampleServletInEar/swagger.json. Ou bien, la valeur de docURL peut commencer par http ou https pour une URL absolue qui identifie l'emplacement complet de la documentation.

      Si l'application Web ne fournit pas de fichier swagger.json ou swagger.yaml et que l'application contient des ressources annotées JAX-RS, vous pouvez générer automatiquement le document Swagger. La configuration de serveur doit comporter la fonction apiDiscovery-1.0 et la fonction jaxrs-1.1 ou jaxrs-2.0. Par exemple :
      <featureManager>
          <feature>apiDiscovery-1.0</feature>
          <feature>jaxrs-1.1</feature>
      </featureManager>
      Le produit analyse toutes les classes de l'application Web pour trouver des annotations JAX-RS et Swagger, en effectuant une recherche sur les classes comportant des annotations @Path, @Api et @SwaggerDefinition. En outre, le produit génère automatiquement un document Swagger correspondant lors du déploiement ou du démarrage de l'application Web.

      Vous pouvez également utiliser la fonction apiDiscovery-1.0 pour fusionner la documentation générée précédemment avec la documentation trouvée lors de l'analyse des annotations. Le produit recherche un fichier META-INF/stub/swagger.json ou META-INF/stub/swagger.yaml dans le module Web. Si la fonction trouve l'un de ces fichiers, elle génère un document Swagger contenant à la fois le contenu du fichier et toute annotation JAX-RS et Swagger contenue dans le module Web. Vous pouvez utiliser cette fonction pour documenter des servlets non JAS-RS car la documentation est fusionnée automatiquement avec les parties JAX-RS.

      Cette technique peut également être utilisée pour ignorer les limitations des annotations, comme l'affichage des définitions de sécurité. Par exemple, le fichier swagger.json suivant, qui se trouve dans META-INF/stub, permet aux annotations de faire référence à ces définitions :

      {
        "swagger" : "2.0",
        "securityDefinitions" : {
          "petstore_auth" : {
            "type" : "oauth2",
            "authorizationUrl" : "http://petstore.swagger.io/api/oauth/dialog,"
            "flow" : "implicit",
            "scopes" : {
              "write_pets" : "modify pets in your account",
              "read_pets" : "read your pets"
            }
          },
          "api_key" : {
            "type" : "apiKey",
            "name" : "api_key",
            "in" : "header"
          }
        }
      }
  3. Lancez une découverte de la documentation de vos API.

    Après avoir configuré l'emplacement de votre documentation d'API, vous pouvez la découvrir (détecter) de différentes façons :

    • Utilisez le point d'extrémité GET https://hôte:port_https/ibm/api/docs.

      Ce point d'extrémité fournit un document Swagger 2.0 valide avec toutes les API REST Liberty disponibles fusionnées en un document unique. Ceci est utile pour les applications client souhaitant parcourir à l'aide d'un programme l'ensemble des API disponibles, par exemple la solution de gestion des API. Le fait d'ajouter un en-tête Accept facultatif avec une valeur application/yaml fournit le document Swagger 2.0 au format YAML. Ce point d'extrémité admet, en option, un paramètre de requête à cardinalité multiple appelé root, qui permet de filtrer les racines de contexte trouvées. Par exemple, un appel à GET https://hôte:port_https/ibm/api/docs?root=/myApp extrait un document Swagger 2.0 qui contient uniquement la documentation de la racine de contexte myApp.

    • Utilisez le point d'extrémité GET https://hôte:port_https/ibm/api/explorer.

      Celui-ci fournit une page HTML au rendu amélioré qui affiche le contenu depuis l'URL /ibm/api/docs. Cette page suit le même schéma que l'exemple en ligne standard (http://petstore.swagger.io/) afin que les utilisateurs puissent démarrer l'API REST. Ce point d'extrémité permet d'explorer les API REST disponibles sur un serveur Liberty, et peut-être de les démarrer depuis la page.

      Une boîte d'entrée de filtre de la page active une liste des racines de contexte séparées par des virgules, pour filtrer le contenu.

    • [17.0.0.1 and later]Utilisez d'autres noeuds finaux pour afficher la documentation REST publique.

      Contrairement aux points d'extrémité mentionnés précédemment, pour être accessibles, ces quatre points d'extrémité n'ont pas besoin d'entrée d'objet keyStore ni d'entrée de registre d'utilisateurs. Vous pouvez cependant créer une entrée d'objet keyStore pour les rendre accessibles à travers HTTPS.

      Par défaut, deux noeuds finaux sont disponibles pour un serveur :
      • GET http://hôte:port_http/api/docs
      • GET http://hôte:port_http/api/explorer

      Vous pouvez changer l'URL des points d'extrémité publics en utilisant l'attribut publicURL dans le fichier server.xml. Par exemple, la configuration suivante dans server.xml permettra de trouver la documentation d'API REST publique avec GET http://hôte:port_http/myAPI/docs et http://hôte:port_http/myAPI/explorer :

      <apiDiscovery publicURL="myAPI" />

      Par défaut, tous les noeuds finaux d'API REST fournis par des applications Web déployés, excepté ceux des serveurs internes tels que ceux des API du connecteur REST, sont visibles dans la documentation d'API REST publique. Vous pouvez masquer les API REST d'un module Web en lui associant l'attribut public="false". Par exemple, en ajoutant la configuration suivante à un fichier server.xml, vous empêchez les API REST du module web désigné de s'afficher dans la documentation d'API REST publique :

      <apiDiscovery publicURL="myAPI">
         <webModuleDoc contextRoot="/22ExampleServlet" public="false" />
      </apiDiscovery>
    • [17.0.0.1 and later]Utilisez un attribut swaggerDefinition dans un fichier server.xml pour remplacer certains champs dans les documents Swagger 2.0 fournis par les points d'extrémité /docs.

      L'attribut swaggerDefinition vous permet de spécifier un fragment Swagger JSON ou YAML contenant les champs à remplacer. Les champs dont les valeurs peuvent être remplacées sont info, schemes, consumes, produces et externalDocs.

    Une fois que vous avez activé la fonction apiDiscovery-1.0, le bean géré (MBean) doté de la valeur ObjectName WebSphere:feature=apiDiscovery,name=APIDiscovery est enregistré dans MBeanServer Liberty. Ce bean géré fournit les attributs suivants :

    • L'attribut DocumentationURL représente l'URL complète du point d'extrémité /ibm/api/docs et affiche la documentation JSON ou YAML brute.
    • L'attribut ExplorerURL représente l'URL complète du point d'extrémité /ibm/api/explorer et affiche l'interface utilisateur rendue de la documentation.

    Vous pouvez utiliser ce bean géré pour savoir si la fonction de découverte d'API REST est activée et si un client peut l'atteindre.

Exemple

Vous trouverez de plus amples informations sur la découverte des API REST dans les interfaces OpenAPI et sur le site Web WASdev.

Vidéo IBM MediaCenter Flash avec présentation audio Regarder : La vidéo IBM WebSphere Application Server Liberty API discovery du Centre multimédia IBM fournit des exemples et des liens vers des vidéos de démonstration. (V8.5.5.9)


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

Nom du fichier : twlp_api_discovery.html