La fonction mpOpenAPI-1.0 fournit une implémentation de la spécification MicroProfile
OpenAPI version 1.0 ainsi qu'un ensemble d'interfaces et modèles de programmation Java permettant aux développeurs
Java de produire en mode natif des documents OpenAPI v3 depuis leur application JAX-RS. Vous pouvez ensuite afficher la documentation d'API générée à l'aide de la fonction mpOpenAPI-1.0
dans un navigateur qui utilise une interface utilisateur conviviale.
Avant de commencer
En savoir plus sur la
spécification OpenAPI V3 et la
spécification MicroProfile OpenAPI 1.0. Vous pouvez utiliser
une fichier OpenAPI statique au format YAML ou JSON, des annotations MicroProfile OpenAPI,
ou des modèles de programmation OpenAPI pour documenter les API RESTful dans votre application.
Eviter les incidents : - Les annotations extension et extensions sont prises en charge uniquement aux niveau opération et classe. Utilisez d'autres mécanismes de documentation pour spécifier des extensions pour d'autres éléments.
- L'interface utilisateur OpenAPI se comporte de manière inattendue si vous avez entré des données d'identification
d'autorisation incorrectes la première fois. Si des données d'identification incorrectes sont entrées ultérieurement,
le problème persiste et entraîner l'affichage répété d'une invite de saisie. Actualisez la page et entrez les données d'identification correctes.
- L'activation de la fonction ssl-1.0 après l'activation de mpOpenAPI-1.0
peut se traduire par des exceptions lorsque vous accédez au noeud final /openapi ou openapi/ui. Pour éviter ce problème, activez les deux fonctions ensemble. Pour résoudre le problème une fois que celui-ci
s'est produit, activez la fonction mpOpenAPI-1.0.
Si plusieurs applications sont déployées, une application est sélectionnée pour produire la documentation OpenAPI. Un message d'information est généré pour identifier l'application sélectionnée. Si cette application est en cours d'exécution,
toutes les autres applications sont ignorées par le processeur d'application. Une fois l'application sélectionnée arrêtée,
l'application suivante est traitée.
Procédure
- Facultatif : Configurez différentes parties de la spécification MicroProfile OpenAPI via le mécanisme MicroProfile
Config selon les besoins de votre application. La fonction mpOpenAPI-1.0 lit les valeurs configurées au démarrage de votre application.
- Configurez une ou plusieurs des configurations Core disponibles depuis la spécifications MicroProfile OpenAPI
pour votre application.
- Pour ajouter une valeur, la fonction mpOpenAPI-1.0 valide le document OpenAPI final
qui est généré pour l'application en fonction des contraintes déclarées dans la spécification OpenAPI version 3.0. Les résultats de la validation, une combinaison d'erreurs et d'avertissements, sont générés dans le journal
de la console.
La validation est activée par défaut pour les applications. Vous pouvez désactiver la validation
en définissant la configuration suivante.
mp.openapi.extensions.liberty.validation=false
- Choisissez l'une des façons ou une combinaison de plusieurs des façons suivantes pour fournir
une entrée à la génération du document OpenAPI comme décrite dans les mécanismes de documentation.
- Utilisez le programmation pour fournir un amorçage ou compléter l'arborescence des modèles OpenAPI.
- Utilisez un éditeur de texte pour écrire un document OpenAPI statique au format YAML ou JSON, puis placez le fichier
openapi.yaml, openapi.yml, ou openapi.json
dans le répertoire META-INF de votre application.
- Spécifiez des annotations MicroProfile OpenAPI dans le code Java pour augmenter et documenter une application.
- Utilisez un filtre pour mettre à jour le modèle OpenAPI après qu'il a été généré
à l'aide des mécanismes de documentation.
- Activez la fonction mpOpenAPI-1.0 dans la configuration du serveur Liberty.
<server>
<featureManager>
<feature>mpOpenAPI-1.0</feature>
</featureManager>
</server>
- Déployez l'application.
- Facultatif : Vérifiez les résultats de la validation et assurez-vous que votre application est conforme à la spécification OpenAPI version 3.0.
- Recherchez dans le journal de la console les erreurs de validation.
- Les événements sont regroupés en erreurs et avertissements. Le message inclut
également l'emplacement correspondant dans le document produit afin de vous aider
à identifier l'élément associé.
Exemple de message :
CWWKO1650E: Validation of the OpenAPI document produced the following error(s):
- Message: Required "scopes" field is missing or is set to an invalid value, Location: #/components/securitySchemes/reviewoauth/flows/authorizationCode
- Affichez le document d'API généré dans un navigateur. Vous pouvez trouver le document d'API généré sur le noeud final /openapi
en utilisant l'une des URL suivantes.
- Pour les API non SSL publiques, affichez votre document à l'adresse http://Liberty_host:http_port/openapi.
- Pour les API SSL publiques, affichez votre document à l'adresse https://Liberty_host:https_port/openapi.
Résultats
L'interface utilisateur OpenAPI rend la définition depuis
/openapi
pour afficher une interface utilisateur sur
http://Liberty_host:http_port/openapi/ui. Si vous activez SSL, vous pouvez accéder à l'interface utilisateur protégée
sur
https://Liberty_host:https_port/openapi/ui.