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

La característica mpOpenAPI-1.1 proporciona una implementación de la especificación de MicroProfile OpenAPI y un conjunto de interfaces Java y modelos de programación que permiten a los desarrolladores Java producir documentos OpenAPI v3 de forma nativa desde la aplicación JAX-RS. A continuación, puede ver la documentación de API generada utilizando la característica mpOpenAPI-1.1 en un navegador que utiliza una interfaz de usuario fácil de usar.

Para obtener información sobre cómo utilizar la característica Liberty MicroProfile OpenAPI versiones 1.0 y posteriores, consulte el sitio web de Open Liberty

Antes de comenzar

Obtenga información sobre la especificaciónOpenAPI V3 y la especificación MicroProfile OpenAPI 1.1 o la especificación MicroProfile OpenAPI 1.0. Puede utilizar un archivo OpenAPI estático en formato YAML o formato JSON, anotaciones de MicroProfile OpenAPI o modelos de programación OpenAPI para documentar las API RESTful en la aplicación.

Evitar problemas:

La extensión y las anotaciones de extensiones sólo se soportan a niveles de operación y clase. Utilice otros mecanismos de documentación para especificar extensiones para otros elementos.
La interfaz de usuario de OpenAPI se comporta de forma inesperada si ha especificado credenciales de autorización incorrectas la primera vez. Si se especifican credenciales correctas posteriormente, el problema persiste y puede solicitar repetidamente las credenciales. Renueve la página y especifique las credenciales correctas.
Si se habilita la característica transportSecurity-1.0 después de habilitar mpOpenAPI-1.1 se pueden producir excepciones cuando se accede a los puntos finales /openapi o openapi/ui. Para evitar el problema, habilite ambas características juntas. Para resolver el problema después de que se produce, inhabilite y, a continuación, habilite la característica mpOpenAPI.

Si se despliegan varias aplicaciones, se selecciona una aplicación para producir la documentación de OpenAPI. Se genera un mensaje informativo para identificar la aplicación que se ha seleccionado. Si la aplicación seleccionada está en ejecución, el procesador de aplicaciones ignora todas las demás aplicaciones. Cuando la aplicación seleccionada se ha detenido, se procesa la siguiente aplicación.

Procedimiento

Opcional: Configure varias partes de la especificación MicroProfile OpenAPI a través del mecanismo MicroProfile config según sea necesario para la aplicación.
La característica mpOpenAPI-1.1 lee los valores configurados cuando se inicia la aplicación.
- Configure una o varias de las configuraciones principales que están disponibles en la especificación MicroProfile OpenAPI para la aplicación.
- Para añadir valor, la característica mpOpenAPI-1.1 valida el documento OpenAPI final que se genera para la aplicación con las restricciones que se declaran en la especificación de OpenAPI versión 3.0. Los resultados de validación, una combinación de errores y avisos, se generan en el registro de consola.
  La validación está habilitada de forma predeterminada para las aplicaciones. Puede inhabilitar la validación estableciendo la siguiente configuración.
```
mp.openapi.extensions.liberty.validation=false
```
Elija una o una combinación de las siguientes formas de proporcionar entrada para la generación del documento OpenAPI resultante tal como se describe en los mecanismos de documentación.
- Utilice el modelo de programación para proporcionar un programa de arranque o completar el árbol de modelos OpenAPI .
- Utilice un editor de texto para escribir un documento OpenAPI estático en formato YAML o JSON y, a continuación, coloque el archivo openapi.yaml, openapi.ymlo openapi.json en el directorio META-INF de la aplicación.
- Especifique MicroProfile OpenAPI annotations en código Java para aumentar y documentar una aplicación.
- Utilice filtro para actualizar el modelo OpenAPI después de que se haya creado utilizando los mecanismos de documentación.

Habilite la característica mpOpenAPI-1.1 en la configuración del servidor de Liberty.

<server>
   <featureManager>
      <feature>mpOpenAPI-1.1</feature>
   </featureManager>
</server>

Despliegue la aplicación.
Opcional: Compruebe los resultados de la validación y asegúrese de que la aplicación se ajusta a la especificación OpenAPI versión 3.0.
- Consulte en el registro de consola los errores de validación.
- Los sucesos se agrupan en errores y avisos. El mensaje también incluye la ubicación correspondiente en el documento producido para ayudarle a identificar el elemento relacionado.
  Mensaje de ejemplo:
```
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
```
Vea el documento de API generado en un navegador.
Puede encontrar el documento de API generado en el punto final /openapi utilizando uno de los siguientes URL.
- Para las API públicas no SSL, consulte su documento en http://Liberty_host:http_port/openapi.
- Para las API públicas de SSL, consulte su documento en https://Liberty_host:https_port/openapi.

Resultados

La interfaz de usuario de OpenAPI representa la definición de /openapi para visualizar una interfaz de usuario en http://Liberty_host:http_port/openapi/ui. Si habilita SSL, puede acceder a la interfaz de usuario protegida en https://Liberty_host:https_port/openapi/ui.