[17.0.0.3 and later]

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 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.

[18.0.0.1 and later]Important : Vous pouvez utiliser les interfaces Java et modèles de programmation disponibles depuis le site

MicroProfile OpenAPI Specification version 1.0. La fonction mpOpenAPI-1.0 implémente la spécification MicroProfile OpenAPI.

Pour plus d'informations sur la fonction mpOpenAPI-1.0, voir Génération d'une documentation d'API REST avec MicroProfile OpenAPI 1.0.

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

  1. Générez la documentation OpenAPI.

    Vous pouvez documenter et générer des des OpenAPI de différentes façons :

    • Spécifiez des annotations OpenAPI en code Java pour étendre 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 en savoir plus sur les interfaces de programmation disponibles, sur les descriptions de leurs fonctions et pour obtenir des exemples d'utilisation, voir Interfaces de programmation OpenAPI V3.

  2. 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 : 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.
        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 : 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.
  3. 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).

  4. 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 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>
  5. 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"/>
  6. Déployez vos applications.
  7. 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.
    [17.0.0.4 and later]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.


Icône indiquant le type de rubrique Rubrique Tâche

Nom du fichier : twlp_api_openapi.html