Détection de la documentation d'API REST sur un serveur Liberty
La fonction de reconnaissance des API vous permet de détecter la documentation de vos API REST sur un serveur Liberty et de rechercher les API REST disponibles. Utilisez l'interface utilisateur Swagger pour appeler les noeuds finaux 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 rechercher
les API REST disponibles.
La fonction apiDiscovery-1.0 active les bundles de détection d'API REST dans le produit. La fonction expose également la documentation provenant des noeuds finaux REST Liberty tels que JMX, si la configuration du serveur utilise la fonction restConnector-1.0, et les collectivités si la configuration de 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 servlet-3.0, jsp-2.2, etc. Vérifiez également que les paramètres de port et de registre d'utilisateurs sont corrects pour l'application déployée.
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 noeuds finaux 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étection des API, chaque application nécessite une valeur javax.ws.rs.@ApplicationPath unique ou la définition d'un mappage d'URL 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 Détection d'interface de programmation recherche une valeur META-INF/swagger.json pour chacun des modules Web. Si aucune valeur META-INF/swagger.json n'est trouvée, la fonction de détection des API 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. 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étection 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.0</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, les fichiers swagger.json et inside META-INF/stub suivants permettent 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.
- Détectez votre documentation d'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 noeud final GET
https://hôte:port_https/ibm/api/docs.
Ce noeud final 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 noeud final possède un paramètre de requête facultatif à 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 noeud final 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 masque que l'exemple en ligne standard (http://petstore.swagger.io/) afin que les utilisateurs puissent appeler l'API REST. Ce noeud final 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. Ce filtrage fonctionne comme le paramètre de requête root. Vous pouvez tester les API en fournissant les valeurs d'entrée et en cliquant sur N'hésitez pas à l'essayer.
- L'attribut DocumentationURL représente l'URL complète du noeud final /ibm/api/docs et affiche la documentation JSON ou YAML brute.
- L'attribut ExplorerURL représente l'URL complète du noeud final /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étection d'API REST est activée et si un client peut l'atteindre.
- Utilisez le noeud final GET
https://hôte:port_https/ibm/api/docs.
Sous-rubriques
- 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.


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twlp_api_discovery
Nom du fichier : twlp_api_discovery.html