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.
La fonction apiDiscovery-1.0 active 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 servlet-3.0, jsp-2.2, etc. Vérifiez également les paramètres de port et de registre d'utilisateurs de 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.
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 active les bundles OSGi des fonctions d'extension afin d'apporter des documents d'API REST à l'ensemble de la documentation "maître". 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 une valeur META-INF/swagger.json est introuvable, la fonction Détection d'interface de programmation 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 comportant le contenu du fichier et les annotations JAX-RS et Swagger qui figurent dans le module. Vous pouvez utiliser cette fonction pour documenter des servlets non JAS-RS car la documentation est fusionnée automatiquement avec les parties JAX-RS.
Si racine_contexte/swagger.json n'est pas disponible, la fonction Détection d'interface de programmation place tout fichier racine_contexte/swagger.yaml dans le document agrégé à partir de /ibm/api/docs et /ibm/api/explorer. La fonction apiDiscovery-1.0 peut gérer swagger.json ou swagger.yaml virtuellement ; en d'autres termes, si l'application Web comporte un fichier server.xml qui configure un attribut docURL, un fichier swagger.json ou swagger.yaml dans le dossier META-INF, ou des annotations JAX-RS et Swagger, l'appel de racine_contexte/swagger.json ou racine_contexte/swagger.yaml renvoie la documentation pour cette autre configuration.
- 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 reguê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 indiquant les valeurs d'entrée requises et en cliquant sur le bouton "Try it out!".
- Pour un contrôleur de collectivité, utilisez le noeud final GET
https://hôte:port_https/ibm/api/collective/docs.
Ce noeud final 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. Ce noeud final comporte deux paramètres de requête facultatif et à cardinalité multiple, appelés root et serverID.
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 de la racine de contexte myApp.
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. Le format fournit le nom de l'hôte suivi d'une virgule (,) suivi du répertoire d'installation suivi d'une virgule (,) suivi du nom du serveur. 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 noeud final GET
https://hôte:port_https/ibm/api/collective/explorer.
Ce noeud final 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 noeud final permet d'explorer les API REST disponibles sur une collectivité entière, 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 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 ("). Si vous souhaitez tester les API à l'aide du bouton "N'hésitez pas à l'essayer", vous devez configurer le partage de ressources d'origine croisée dans le fichier server.xml du serveur membre.
Par exemple, le fragment 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 en savoir plus sur la configuration de CORS, voir 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 de collectivité de l'interface utilisateur Swagger (https://host:https_port/ibm/api/collective/explorer).
- 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. - Abonnement afin de recevoir des mises à jour des API REST Liberty dans une collectivité
Utilisez l'API d'abonnement du contrôleur de collectivité pour découvrir immédiatement les API REST qui ont été ajoutées, retirées ou les modifications apportées aux API, telles que les changements effectués sur des noeuds finaux à partir d'un serveur membre de collectivité 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.
Rubrique Tâche
Dernière mise à jour: 7 juin 2016http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-dist&topic=twlp_api_discovery
Nom du fichier : twlp_api_discovery.html
