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 sus API REST, especifique las API públicas y privadas, elija habilitar el escaneo de anotaciones e implemente sus 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.

Características estabilizadas: Las características OpenAPI V3, openapi-3.0 y openapi-3.1, se han estabilizado. Puede continuar utilizando las características. Sin embargo, la alternativa estratégica es utilizar una función de MicroProfile OpenAPI como mpOpenAPI-3.0.

Para obtener más información sobre cómo utilizar MicroProfile OpenAPI con Liberty, consulte el sitio web Open Liberty.

Antes de comenzar

Más información sobre la especificación « OpenAPI » ( V3 ). Utilice archivos YAML o JSON para documentar las API RESTful en las aplicaciones.

Puede utilizar las interfaces y los modelos de programación Java disponibles en la especificación MicroProfileOpenAPI, versión 1.0. La característica mpOpenAPI-1.0 implementa la especificación MicroProfile OpenAPI. Para obtener más información sobre las mpOpenAPI-1.0 funciones y posteriores, consulte Generar documentación de la API REST con MicroProfile OpenAPI.

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.

Pruebe a documentar una aplicación RESTful utilizando anotaciones OpenAPI en código Java™ con la aplicación de ejemplo de anotaciones OpenAPI V3.
Vea un ejemplo de un documento OpenAPI V3 en formato YAML creado con un editor de texto con OpenAPI V3 documento de ejemplo.
Amplíe la openapi-3.0 funcionalidad utilizando las io.swagger.oas.integration.OpenAPIConfigurationBuilder interfaces de programación con el ejemplo de interfaz de programación OpenAPIConfiguration.

Procedimiento

Genere la documentación de OpenAPI.
Puede documentar y generar OpenAPIs en varias formas:
- Especifique anotaciones de OpenAPI en el código Java para ampliar 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.
  Para obtener más información sobre las interfaces de programación disponibles, descripciones de sus capacidades y ejemplos de su uso, consulte OpenAPI Interfaces de programación de V3.
Habilite la openapi-3.0 función en la configuración del servidor Liberty.
1. Añadir la openapi-3.0 función al gestor de funciones.
```
<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 aparezca en el documento « 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 enabled atributo no es compatible con los documentos de la API REST proporcionados por otras funciones de Liberty.
Opcional: habilitar el escaneo 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).
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 visibilidad de la API de terceros para la aplicación específica.
1. Defina el apiTypeVisibility atributo del classloader elemento como visibilidad de API de terceros. Añade third-party al classloader elemento en tu server.xml archivo.
  
  Si no especifica classloader para incluir third-party en apiTypeVisibility, utiliza la definición predeterminar de spec, stable y ibm-api.
```
<application id="scholar" name="Scholar" type="ear" location="scholar.ear">
  <classloader apiTypeVisibility="spec, ibm-api, stable, third-party" commonLibraryRef="Alexandria" />
</application>
```
Opcional: Habilitar la validación de documentos OpenAPI.

La capacidad de validación está inhabilitada de forma predeterminada. 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"/>
```
Despliegue las aplicaciones.
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 las API públicas no SSL, consulte su documento en http://Liberty_host:http_port/api/docs.
- Para las API públicas de SSL, consulte su documento en https://Liberty_host:https_port/api/docs.
- Para las API privadas de SSL, consulte su documento en https://Liberty_host:https_port/ibm/api/docs.
Consejo: De forma predeterminada, hay dos puntos finales disponibles para un servidor.
- GET http://Liberty_host:http_port/api/docs
- GET http://Liberty_host:http_port/api/explorer
Puede personalizar las URL de los puntos finales públicos con el publicURL atributo en el server.xml archivo. El siguiente ejemplo ilustra la configuración del server.xml archivo para que la documentación pública de la API REST esté disponible con GET http://Liberty_host:http_port/myAPI/docs and http://Liberty_host:http_port/myAPI/explorer.
```
<openapi publicURL="myAPI" />
```
El documento « OpenAPI » se genera y se agrega en todas las aplicaciones de ese servidor Liberty. El documento tiene formato YAML de forma predeterminada. Cuando visualizas tu documentación con Microsoft Internet Explorer 11, devuelve un documento YAML que no está formateado correctamente. Como solución alternativa, utilice un navegador como 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://Liberty_host:http_port/api/docs?root=/myApp recupera un documento OpenAPI V3 que solo contiene la documentación de la myApp raíz de contexto.

Resultados

La interfaz de usuario OpenAPI muestra las definiciones agregadas de /api/docs para mostrar una interfaz de usuario fácil de usar en http://Liberty_host:http_port/api/explorer. Si habilita SSL, puede acceder a la interfaz de usuario protegida en https://Liberty_host:https_port/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 la navegación privada por módulos web está habilitada, utilice https://Liberty_host:https_port/ibm/api/explorer para mostrar la interfaz de usuario intuitiva tanto para módulos web públicos como 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.