Génération d'une documentation d'API REST avec OpenAPI

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 des annotations et déployez vos applications Web sur 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.

Fonctions stabilisées: les fonctions OpenAPI V3 , openapi-3.0 et openapi-3.1, sont stabilisées. Vous pouvez continuer de les utiliser. Toutefois, l'alternative stratégique consiste à utiliser une fonction MicroProfile OpenAPI telle que mpOpenAPI-3.0.

Pour plus d'informations sur l'utilisation de MicroProfile OpenAPI avec Liberty, voir le site Web Open Liberty

Avant de commencer

Découvrez la spécificationOpenAPI V3. Vous utilisez des fichiers YAML ou JSON pour documenter les API RESTful dans vos applications.

Vous pouvez utiliser les interfaces Java et les modèles de programmation disponibles dans MicroProfile OpenAPI Specification version 1.0. La fonction mpOpenAPI-1.0 met en œuvre la spécification MicroProfile OpenAPI. Pour plus d'informations sur les fonctions mpOpenAPI-1.0 et ultérieures, voir Génération de la documentation de l'API REST avec MicroProfile OpenAPI.

A propos de 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.

Essayez de documenter une application RESTful à l'aide d'annotations OpenAPI dans le code Java™ à l'aide de l' exemple d'application d'annotationOpenAPI V3.
Voir un exemple de document OpenAPI V3 au format YAML créé avec un éditeur de texte avec un exemple de documentOpenAPI V3.
Etendez la fonction openapi-3.0 en utilisant les interfaces de programmation io.swagger.oas.integration.OpenAPIConfigurationBuilder avec l' exemple d'interface de programmationOpenAPIConfiguration.

Procédure

Générez la documentation OpenAPI.
Vous pouvez documenter et générer des OpenAPI de différentes façons :
- Spécifiez des annotations OpenAPI dans le code Java pour augmenter et documenter une application.
- Utilisez un éditeur de texte pour documenter l'API avec des balises OpenAPI, puis placez le fichier openapi.yaml, openapi.yml ou openapi.json complété dans le répertoire META-INF de votre application.
- Utilisez les interfaces de programmation io.swagger.oas.integration.OpenAPIConfigurationBuilder pour générer le modèle OpenAPI à partir de l'application. Cette interface et les autres interfaces de programmation associées de OpenAPI V3 se trouvent dans les fichiers JAR du répertoire /wlp/dev/api/third-party. Pour que la fonction openapi-3.0 démarre l'interface OpenAPIConfigurationBuilder, l'archive d'application doit contenir un fichier META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder. Le contenu de ce fichier est le nom complet de OpenAPIConfigurationBuilder.
  Pour plus d'informations sur les interfaces de programmation disponibles, des descriptions de leurs fonctions et des exemples d'utilisation, voir OpenAPI V3 programming interfaces.
Activez la fonction openapi-3.0 dans la configuration du serveur Liberty .
1. Ajoutez la fonction openapi-3.0 au gestionnaire de fonctions.
```
<server>
   <featureManager>
      <feature>openapi-3.0</feature>
   </featureManager>
</server>
```
2. Facultatif: Indiquez 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.
    1. Ajoutez un élément openapi et définissez son attribut booléen enablePrivateURL sur true.
    2. 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.
    1. Ajoutez un élément openapi à la configuration du serveur et définissez son attribut booléen enablePrivateURL sur true.
    2. 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.
3. Facultatif: Indiquez qu'une application n'apparaît pas 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: Activez l'analyse des annotations 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 sur 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.
1. Définissez l'attribut apiTypeVisibility de l'élément classloader en tant que visibilité d'API tierce. 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, stable et ibm-api.
```
<application id="scholar" name="Scholar" type="ear" location="scholar.ear">
  <classloader apiTypeVisibility="spec, ibm-api, stable, third-party" commonLibraryRef="Alexandria" />
</application>
```
Facultatif: Activez la validation des documents OpenAPI .

La fonction de validation est désactivée 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 publiques non SSL, affichez votre document à l'adresse http://Liberty_host:http_port/api/docs.
- Pour les API publiques SSL, affichez votre document à l'adresse https://Liberty_host:https_port/api/docs.
- Pour les API SSL privées, affichez votre document à l'adresse https://Liberty_host:https_port/ibm/api/docs.
Astuce: 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é entre les 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é. Comme solution palliative, 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.

Astuce: 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 à GET http://Liberty_host:http_port/api/docs?root=/myApp extrait un document OpenAPI V3 qui ne contient que la documentation de la racine de contexte myApp .

Résultats

L'interface utilisateur OpenAPI rend les définitions agrégées de /api/docs pour afficher une interface utilisateur conviviale à l'adresse http://Liberty_host:http_port/api/explorer. Si vous activez SSL, vous pouvez accéder à l'interface utilisateur protégée à l'adresse https://Liberty_host:https_port/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 la navigation dans le module Web privé est activée, utilisez https://Liberty_host:https_port/ibm/api/explorer pour afficher l'interface utilisateur conviviale 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.