Vous pouvez générer votre documentation d'API REST à l'aide de la fonction openapi-3.0 conforme à la spécification OpenAPI. Documentez vos API REST, spécifiez des
API publiques et privées, choisissez d'activer l'analyse d'annotations et déployez vos applications Web dans un serveur Liberty. Vous
pouvez ensuite afficher la documentation d'API généré par openapi-3.0 dans un navigateur utilisant une interface utilisateur conviviale.
Avant de commencer
En savoir plus sur la spécification OpenAPI V3. Vous utilisez des fichiers
YAML ou JSON pour documenter les API RESTful dans vos applications.
Pourquoi et quand exécuter cette tâche
Vous pouvez explorer ces fonctions, comme la nouvelle interface utilisateur, les annotations et les interfaces de programmation avec les exemples d'application suivants.
Procédure
- Générez la documentation OpenAPI.
Vous pouvez documenter et générer des des OpenAPI de différentes façons :
- Activez la fonction openapi-3.0 dans la configuration du serveur Liberty.
- Ajoutez la fonction openapi-3.0 au gestionnaire de fonctions.
<server>
<featureManager>
<feature>openapi-3.0</feature>
</featureManager>
</server>
- Facultatif : Spécifiez qu'une application OpenAPI est privée.
Par défaut, la documentation OpenAPI est publique. Tous les utilisateurs peuvent accéder aux API publiques, souvent sans authentification. Les API publiques sont documentées dans la ressource
/api/docs.
Vous pouvez spécifier que les API restent privées. Les API utilisées à des fins administratives restent généralement privées.
Les API privées, qui sont protégées par des mots de passe, sont documentées dans la ressource /ibm/api/docs. Cette ressource documente toutes les API privées et toutes les
API publiques.
Vous pouvez spécifier des API privées pour les applications de deux manières :
- Utilisez webModuleDoc dans la configuration du serveur, avec l'attribut public défini sur false.
- Ajoutez un élément openapi et définissez son attribut booléen enablePrivateURL sur true.
- Ajoutez un sous-élément webModuleDoc pour chaque application Web et définissez son attribut booléen public sur true pour les API publiques
et sur false pour les API privées.
L'exemple suivant rend les OpenAPI de l'application airlines visibles et les OpenAPI de l'application airlinesAdmin non visibles.
<openapi enablePrivateURL="true">
<webModuleDoc contextRoot="/airlines" public="true" />
<webModuleDoc contextRoot="/airlinesAdmin" public="false" />
</openapi>
Par défaut, l'attribut public de webModuleDoc est défini sur true. Cette configuration est uniquement requise pour désactiver
les applications que vous souhaiter garder privées.
- Utilisez un mot-clé d'extension de fournisseur dans la description d'API pour indiquer qu'une API est privée.
- Ajoutez un élément openapi à la configuration du serveur et définissez son attribut booléen enablePrivateURL sur true.
- Entrez le mot-clé et la valeur x-ibm-private: true dans le fichier META-INF/openapi.yaml du document de description d'API ou dans le fichier d'un autre
format pris en charge. Cette valeur ignore la visibilité par défaut de l'API et cette valeur peut être remplacée par une entrée webModuleDoc.
- Facultatif : Spécifiez qu'aucune application n'apparaît dans le document OpenAPI.
Par défaut, vos modules Web contenant les documents d'API REST apparaissent dans le document OpenAPI fusionné disponible dans la ressource /api/docs. Pour éviter que les
modules Web n'apparaissent dans le document OpenAPI, modifiez les attributs de l'élément webModuleDoc dans la configuration du serveur.
Identifiez le module Web que vous souhaitez masquer ou afficher avec l'attribut contextRoot. Changez ensuite l'attribut enabled sur
false pour masquer le module Web dans le document OpenAPI. La valeur par défaut de l'attribut enabled est true. Dans l'exemple
suivant, le module airlines est configuré de façon à apparaître dans le document OpenAPI alors le module airlinesAdmin est masqué.
<openapi>
<webModuleDoc contextRoot="/airlines" enabled="true" />
<webModuleDoc contextRoot="/airlinesAdmin" enabled="false" />
</openapi>
Remarque : L'attribut enabled n'est pas pris en charge pour les documents d'API REST fournis par d'autres fonctions Liberty.
- Facultatif : Activation de l'analyse d'annotation JAX-RS.
Ajoutez la fonction jaxrs-2.0 au gestionnaire de fonctions. Lorsque les fonctions jaxrs-2.0 et openapi-3.0 sont activées dans un
serveur, l'analyseur d'annotation analyse toutes les applications Web déployées sur le serveur à moins que la configuration du serveur désactive l'analyse. L'analyseur passe en revue les classes
qui sont annotées avec les annotations OpenAPI 3.0 sur la définition de classe et annotées avec l'annotation JAX-RS @Path. Vous pouvez accéder aux documents OpenAPI
générés avec le noeud final public OpenAPI (api/docs) et le noeud final privé (ibm/api/docs).
- Autorisez la visibilité des API par les tiers pour certaines applications. Pour activer le chargement en phase d'exécution des annotations OpenAPI, des modèles et des modèles de programmation, vous devez activer la visibilité des API par les tiers pour
l'application spécifique.
- Définissez l'attribut apiTypeVisibility de l'élément classloader en tant que visibilité d'API par les tiers. Ajoutez third-party à
l'élément classloader dans votre fichier server.xml.
Si vous ne spécifiez pas classloader pour inclure third-party dans apiTypeVisibility, il utilise la définition par défaut de
spec et ibm-api.
<application id="scholar" name="Scholar" type="ear" location="scholar.ear">
<classloader apiTypeVisibility="spec, ibm-api, third-party" commonLibraryRef="Alexandria" />
</application>
- Facultatif : Activez la validation des documents OpenAPI.
La fonction de validation n'est pas disponible par défaut. Lorsque vous activez la validation, chaque document OpenAPI fourni par l'application est comparés aux contraintes déclarées dans la
spécification OpenAPI V3 par la fonction openapi-3.0. Si openapi-3.0 trouve un document OpenAPI qui n'est pas valide, la fonction signale une erreur dans
les journaux pour chaque contrainte enfreinte. Le document non valide est exclu du document OpenAPI agrégé qui est renvoyé par le noeud final api/docs. Pour activer la
validation, définissez l'attribut validation sur true dans le fichier server.xml.
<openapi validation="true"/>
- Déployez vos applications.
- Affichez le document d'API généré dans un navigateur.
Vous trouverez le document d'API généré au niveau du noeud final /api/docs à l'aide de l'une des URL suivantes, suivant si votre API est publique ou privée.
- Pour les API non SSL publiques, affichez votre document à l'adresse http://hôte_Liberty:port_http/api/docs.
- Pour les API SSL publiques, affichez votre document à l'adresse https://hôte_Liberty:port_https/api/docs.
- Pour les API SSL privées, affichez votre document à l'adresse https://hôte_Liberty:port_https/ibm/api/docs.
Conseil : Par défaut, deux noeuds finaux sont disponibles pour un serveur.
- GET http://Liberty_host:http_port/api/docs
- GET http://Liberty_host:http_port/api/explorer
Vous pouvez personnaliser les URL des points finaux publics en utilisant l'attribut
publicURL dans le fichier
server.xml. L'exemple ci-dessous illustre la configuration dans le fichier
server.xml qui permet de rendre la documentation API REST publique disponible avec
GET http://Liberty_host:http_port/myAPI/docs and
http://Liberty_host:http_port/myAPI/explorer.
<openapi publicURL="myAPI" />
Le document OpenAPI est généré et agrégé dans les différentes applications pour ce serveur Liberty. Le document est au format YAML
par défaut. Lorsque vous affichez votre documentation avec Microsoft Internet Explorer 11, il renvoie un document YAML qui n'est pas correctement
formaté. Pour régler ce problème, utilisez un navigateur tel que Mozilla Firefox ou Google Chrome. Si la
demande http contient une en-tête Accept avec une valeur application/json, le document est au format JSON.
Conseil : Vous pouvez filtrer le document OpenAPI par racine de contexte. Le noeud final public (api/docs) comme le noeud final privé
(ibm/api/docs) prennent en charge un paramètre de requête, root, qui peut filtrer les racines de contexte trouvées. Par exemple, un appel de GET
http://hôte_Liberty:port_http/api/docs?root=/myApp extrait un document OpenAPI V3 qui contient uniquement la
documentation de la racine de contexte myApp.
Résultats
L'interface utilisateur d'OpenAPI rend les définitions agrégées de /api/docs sous la forme d'une interface utilisateur conviviale pour l'homme à l'adresse :
http://hôte_Liberty:port_http/api/explorer.
Si vous activez SSL, vous pouvez accéder à l'interface utilisateur protégée à l'adresse
https://hôte_Liberty:port_https/api/explorer.
Vous pouvez accéder aux modules Web privés en activant l'attribut
enablePrivateURL dans l'élément
openAPI du fichier
server.xml.
<openapi enablePrivateURL="true"/>
Lorsque l'accès au module Web privé est activé, utilisez
https://hôte_Liberty:port_https/ibm/api/explorer pour afficher une interface utilisateur conviviale pour l'homme à la fois pour les
modules Web publics et privés.
Vous pouvez afficher tous les noeuds finaux RESTful de votre application dans cette interface utilisateur. Vous pouvez également filtrer les noeuds finaux affichés pour vous concentrer sur
des applications spécifiques.