[17.0.0.3 and later]

Generación de documentación de la API REST con OpenAPI

Puede generar la documentación de la API REST utilizando la característica openapi-3.0. que admite la especificación de OpenAPI. Documente las API REST, especifique API públicas y privadas, elija habilitar la exploración de anotaciones y despliegue las aplicaciones web en un servidor Liberty. A continuación, puede ver la documentación de la API generada por openapi-3.0 en un navegador que utiliza una interfaz de usuario práctica para el usuario.

Antes de empezar

Obtenga más información sobre la especificación de OpenAPI V3. Utilice archivos YAML o JSON para documentar las API RESTful en las aplicaciones.

[18.0.0.1 and later]Importante: Puede utilizar las interfaces Java y los modelos de programación que están disponibles en la

Especificación MicroProfile OpenAPI versión 1.0. La característica mpOpenAPI-1.0 implementa la especificación MicroProfile OpenAPI.

Para obtener más información sobre la característica mpOpenAPI-1.0, consulte Generación de documentación de API REST con OpenAPI MicroProfile 1.0.

Acerca de esta tarea

Puede explorar estas características como, por ejemplo, la nueva interfaz de usuario, anotaciones e interfaces de programación, con las aplicaciones de ejemplo siguientes.

Procedimiento

  1. Genere la documentación de OpenAPI.

    Puede documentar y generar OpenAPIs en varias formas:

    • Especifique anotaciones OpenAPI en código Java para aumentar y documentar una aplicación.
    • Utilice un editor de texto para documentar la API con etiquetas OpenAPI y, después, coloque el archivo completado openapi.yaml, openapi.yml o openapi.json en el directorio META-INF de la aplicación.
    • Utilice las interfaces de programación io.swagger.oas.integration.OpenAPIConfigurationBuilder para generar el modelo OpenAPI desde la aplicación. Esta interfaz, y las otras interfaces de programación relacionadas para OpenAPI V3, se puede encontrar en los archivos JAR del directorio /wlp/dev/api/third-party. Para que la característica openapi-3.0 inicie OpenAPIConfigurationBuilder, el archivado de la aplicación debe tener un archivo META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder. El contenido de este archivo es el nombre completo de OpenAPIConfigurationBuilder.

      Si desea más información sobre las interfaces de programación disponibles, descripciones de sus prestaciones y ejemplos de su uso, consulte Interfaces de programación OpenAPI V3.

  2. Habilite la característica openapi-3.0 en la configuración del servidor Liberty.
    1. Añada la característica openapi-3.0 al gestor de características.
      <server>
         <featureManager>
            <feature>openapi-3.0</feature>
         </featureManager>
      </server>
    2. Opcional: Especifique que una aplicación OpenAPI es privada.

      De forma predeterminada, la documentación de OpenAPI es pública. Todos los usuarios pueden acceder a API públicas, a menudo, sin autenticación. Las API públicas se documentan en el recurso /api/docs.

      Puede especificar que las API permanecen privadas. Las API para un uso administrativo normalmente se mantienen privadas. Las API privadas, que utilizan contraseñas para la protección, se documentan en el recurso /ibm/api/docs. Este recurso documenta todas las API privadas y todas las API públicas.

      Puede especificar API privadas para aplicaciones web de dos formas:

      • Utilice webModuleDoc en la configuración del servidor, con el atributo public establecido en false.
        1. Añada un elemento openapi y establezca su atributo booleano enablePrivateURL en true.
        2. Añada un subelemento webModuleDoc para cada aplicación web y establezca su atributo booleano public en true para API públicas y en false para API privadas.

        El ejemplo siguiente hace que las OpenAPI de la aplicación de aerolíneas estén visibles e inhabilita la exposición de las OpenAPI de la aplicación airlinesAdmin.

        <openapi enablePrivateURL="true">
          <webModuleDoc contextRoot="/airlines" public="true" />
          <webModuleDoc contextRoot="/airlinesAdmin" public="false" />
        </openapi>

        De forma predeterminada, el atributo public de webModuleDoc está establecido en true. Esta configuración solo es necesaria para inhabilitar las aplicaciones que desea mantener privadas.

      • Utilice una palabra clave de ampliación de proveedor en la descripción de la API para designar que una API es privada.
        1. Añada un elemento openapi a la configuración del servidor y establezca su atributo boleano enablePrivateURL en true.
        2. Coloque la palabra clave x-ibm-private: true y un valor en el archivo META-INF/openapi.yaml del documento de descripción de API, o en el archivo de otro formato soportado. Este valor altera temporalmente la visibilidad predeterminada de la API y este valor se puede alterar temporalmente mediante una entrada webModuleDoc.
    3. Opcional: Especifique que una aplicación no aparece en el documento de OpenAPI.

      De forma predeterminada, los módulos web que contienen documentos de API REST aparecen en el documento de API OpenAPI fusionado disponible en el recurso /api/docs. Para que los módulos web sigan apareciendo en el documento de OpenAPI, cambie los atributos del elemento webModuleDoc en la configuración del servidor.

      Identifique el módulo web que desea ocultar o mostrar con el atributo contextRoot. A continuación, cambie el atributo enabled a false para ocultar el módulo web del documento de OpenAPI. El valor predeterminado para el atributo enabled es true. En el ejemplo siguiente, el módulo de aerolíneas se ha configurado de forma que aparece en el documento de OpenAPI mientras que el módulo airlinesAdmin está oculto.

      <openapi>
        <webModuleDoc contextRoot="/airlines" enabled="true" />
        <webModuleDoc contextRoot="/airlinesAdmin" enabled="false" />
      </openapi>
      Nota: El atributo enabled no está soportado para documentos de API REST proporcionados por otras características de Liberty.
  3. Opcional: Habilite la exploración de anotaciones JAX-RS.

    Añada la característica jaxrs-2.0 al gestor de características. Cuando ambas características, jaxrs-2.0 y openapi-3.0, están habilitadas en un servidor, el explorador de anotaciones explora todas las aplicaciones web que se han desplegado en el servidor, a menos que la configuración del servidor inhabilite la exploración. El explorador pasa por las clases que están anotadas con las anotaciones OpenAPI 3.0 en la definición de clase y que están anotadas con la anotación JAX-RS @Path. Puede acceder a documentos de OpenAPI generados con el punto final público OpenAPI (api/docs) y el punto final privado (ibm/api/docs).

  4. Permita la visibilidad de API de terceros para aplicaciones específicas. Para habilitar la carga de tiempo de ejecución de anotaciones OpenAPI, modelo y modelos de programación, debe habilitar la visibilidadde la API de terceros para la aplicación específica.
    1. Defina el atributo apiTypeVisibility del elemento classloader como visibilidad de API de terceros. Añada third-party al elemento classloader en el archivo server.xml.

      Si no especifica classloader para incluir third-party en apiTypeVisibility, utiliza la definición predeterminada de spec y ibm-api.

      <application id="scholar" name="Scholar" type="ear" location="scholar.ear">
        <classloader apiTypeVisibility="spec, ibm-api, third-party" commonLibraryRef="Alexandria" />
      </application>
  5. Opcional: Habilite la validación de documentos OpenAPI.

    La prestación de validación no está disponible de forma disponible. Al habilitar la validación, cada documento OpenAPI proporcionado por la aplicación se valida con respecto a las restricciones declaradas en la especificación de OpenAPI V3 mediante la característica openapi-3.0. Si openapi-3.0 encuentra un documento OpenAPI que no es válido, la característica notifica un error en los registros para restricción violada. El documento no válido se excluye del documento OpenAPI agregado devuelto por el punto final api/docs. Para habilitar la validación, establezca el atributo validation en true en el archivo server.xml.

    <openapi validation="true"/>
  6. Despliegue las aplicaciones.
  7. Vea el documento de API generado en un navegador.

    Puede encontrar el documento de API generado en el punto final /api/docs utilizando uno de los URL siguientes, en función de si la API es pública o privada.

    • Para API públicas no SSL, vea el documento en http://host_Liberty:puerto_http/api/docs.
    • Para API públicas de SSL, vea el documento en https://host_Liberty:puerto_https/api/docs.
    • Para API privadas de SSL, vea el documento en https://host_Liberty:puerto_http/ibm/api/docs.
    [17.0.0.4 and later]Consejo: De forma predeterminada, hay dos puntos finales disponibles a un servidor.
    • GET http://Liberty_host:http_port/api/docs
    • GET http://Liberty_host:http_port/api/explorer
    Se pueden personalizar los URL de los puntos finales públicos con el atributo publicURL en el archivo server.xml. El ejemplo siguiente ilustra la configuración en el archivo server.xml para hacer que la documentación del API REST pública esté disponible con GET http://Liberty_host:http_port/myAPI/docs y http://Liberty_host:puerto_http/myAPI/explorer.
    <openapi publicURL="myAPI" />

    El documento OpenAPI se genera y agrega entre aplicaciones para dicho servidor Liberty. El documento tiene formato YAML de forma predeterminada. Al ver la documentación con Microsoft Internet Explorer 11, devuelve un documento YAML que no tiene un formato adecuado. Como solución temporal, utilice un navegador como, por ejemplo, el navegador Mozilla Firefox o Google Chrome. Si la solicitud http tiene una cabecera Accept con un valor application/json, el documento está en formato JSON.

    Consejo: Puede filtrar el documento OpenAPI por raíz de contexto. Tanto el punto final público (api/docs) como el punto final privado (ibm/api/docs) soportan un parámetro de consulta, root, que puede filtrar las raíces de contexto encontradas. Por ejemplo, una llamada a GET http://host_Liberty:puerto_http/api/docs?root=/myApp recupera un documento OpenAPI V3 que solo tiene la documentación para la raíz de contexto myApp.

Resultados

La interfaz de usuario OpenAPI representa las definiciones agregadas de /api/docs para mostrar una interfaz de usuario práctica para el usuario en http://host_Liberty:puerto_http/api/explorer. Si habilita SSL, puede acceder a la interfaz de usuario protegida en https://host_Liberty:puerto_https/api/explorer.

Puede examinar los módulos web privados habilitando el atributo enablePrivateURL en el elemento openAPI del archivo server.xml.
<openapi enablePrivateURL="true"/>
Cuando está habilitada la exploración de módulos web privados, utilice https://host_Liberty:puerto_https/ibm/api/explorer para mostrar la interfaz de usuario práctica para el usuario para ambos módulos web, públicos y privados.

Puede ver todos los puntos finales RESTful desde la aplicación en esta interfaz de usuario. También puede filtrar puntos finales visualizados para centrarse en aplicaciones específicas.


Icono que indica el tipo de tema Tema de tarea

Nombre de archivo: twlp_api_openapi.html