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 appeler les points d'extrémité REST disponibles.
Procédure
- 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 expose é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 voulez exposer 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.
En revanche, si vous exposez seulement 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>
- Exposez 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'exposer 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'exposer 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 exposer 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 :
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.<featureManager> <feature>apiDiscovery-1.0</feature> <feature>jaxrs-1.1</feature> </featureManager>
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'exposition 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" } } }
- Utilisez la méthode getDocument de l'interface SPI com.ibm.wsspi.rest.api.discovery.APIProvider.
- 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 appeler l'API REST. Ce point d'extrémité permet d'explorer les API REST disponibles sur un serveur Liberty, et peut-être de les appeler 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.
Utilisez d'autres noeuds finaux pour exposer 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 contribuées 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>
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.
- Utilisez le point d'extrémité GET
https://hôte:port_https/ibm/api/docs.
Sous-rubriques
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.- Abonnement afin de recevoir les mises à jour des API REST Liberty
La fonction de détection des API REST Liberty propose désormais une nouvelle API REST, /ibm/api/docs/subscription, qui permet aux utilisateurs de s'abonner afin de recevoir les mises à jour relatives aux API REST, par exemple, les nouvelles API disponibles ou les anciennes API retirées. Ceci est pratique lorsqu'un utilisateur désire être immédiatement avisé des modifications des noeuds finaux fournis par une instance Liberty spécifique. - Noeuds finaux REST pour envoi d'API dans IBM API Connect
Utilisez le noeud final REST, qui est un emplacement central pour les utilisateurs Liberty sur site et dans le cloud, pour visualiser, appeler et envoyer des API dans IBM® API Connect.

Nom du fichier : twlp_api_discovery.html