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.

    La fonction apiDiscovery-1.0 qui est activée sur un serveur de contrôleur de collectivité Liberty recherche les API REST disponibles sur le contrôleur et ses serveurs membres avec la fonction apiDiscovery-1.0 activée.

    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.

    • Pour un contrôleur de collectivité, utilisez le point d'extrémité GET https://hôte:port_https/ibm/api/collective/docs.

      Ce point d'extrémité sur le contrôleur de collectivité fournit un document Swagger 2.0 valide avec les API REST disponibles à partir du contrôleur de collectivité et de ses membres avec la fonction apiDiscovery-1.0 activée fusionné dans 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.

      [17.0.0.1 and later]Ce point d'extrémité n'accepte qu'un seul paramètre de requête, optionnel et à cardinalité multiple, appelé root.

      Le paramètre de requête root permet de filtrer les racines de contexte trouvées. Par exemple, un appel à GET https://hôte:port_https/ibm/api/collective/docs?root=/myApp extrait un document Swagger 2.0 qui contient uniquement la documentation pour la racine de contexte myApp.

      [16.0.0.x]Pour les versions antérieures à la version 17.0.0.1, ce noeud final a deux paramètres de requête facultatifs, à cardinalité multiple, nommés root et serverID. Le paramètre de requête root est le même qu'auparavant. Le paramètre de requête serverID permet de filtrer les API REST disponibles à partir d'un serveur Liberty. Le format de serverID est nomHôte,répUtilisateur,nomServeur. Par exemple, un appel à GET https://hôte:port_https/ibm/api/collective/docs?serverID=samplehost.com:8020,/users/admin/wlp/usr,server1 extrait un document Swagger 2.0 qui comporte uniquement la documentation des API REST disponibles à partir du serveur Liberty avec l'ID serveur (serverID) spécifié.

    • Pour un contrôleur de collectivité, utilisez le point d'extrémité GET https://hôte:port_https/ibm/api/collective/explorer.

      Ce point d'extrémité sur le contrôleur de collectivité fournit une page HTML au rendu amélioré qui affiche le contenu depuis l'URL /ibm/api/collective/docs. Ce point d'extrémité permet d'explorer les API REST disponibles sur une collectivité entière, 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 et d'ID serveur séparés par des virgules, pour filtrer le contenu. Le format de l'ID serveur est "nomHôte,répUtilisateur,nomServeur". L'ID serveur doit être placé entre guillemets ("). Pour tester les API avec le bouton N'hésitez pas à l'essayer, vous devez configurer le partage de ressources d'origine croisée (CORS) dans le fichier server.xml du serveur membre.​

      [16.0.0.x]Pour les versions antérieures à la version 17.0.0.1, un fragment similaire à l'exemple suivant est requis dans le fichier server.xml du serveur membre qui fournit l'API /IBMJMXConnectorREST/mbeanCount.
      <cors domain="/IBMJMXConnectorREST/mbeanCount"
            allowedOrigins="https://controller_hostname:https_port"
            allowedMethods="GET,POST,DELETE,PUT,PATCH,OPTIONS"
            allowedHeaders="Content-Type,api_key,Authorization"
            allowCredentials="true" />

      Pour des informations sur la configuration du partage de ressources d'origine croisée, consultez Configuration du partage de ressources d'origine croisée sur un serveur Liberty.

      Remarque : Les exigences relatives au partage de ressources d'origine croisée s'appliquent uniquement à la version "collective" de l'interface utilisateur Swagger (https://host:https_port/ibm/api/collective/explorer).
    • [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, quatre noeuds finaux sont disponibles pour un contrôleur de collectivité :
      • GET http://hôte:port_http/api/docs
      • GET http://hôte:port_http/api/explorer
      • GET http://hôte:port_http/api/collective/docs
      • GET http://hôte:port_http/api/collective/explorer
      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.

    • [17.0.0.1 and later]Pour un contrôleur de collectivité, utilisez une requête sur les services de la collectivité pour obtenir la liste de toutes les API (services) RESTful publiques disponibles dans la collectivité entière.

    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