La característica mpOpenAPI-1.0 proporciona una implementación de la especificación
de MicroProfile OpenAPI versión 1.0 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.0 en un navegador que utiliza una interfaz de usuario fácil de usar.
Antes de empezar
Obtenga información sobre la
especificación de OpenAPI V3 y la
especificación de 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.
Evite 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 ssl-1.0 después de habilitar
mpOpenAPI-1.0 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-1.0.
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 diversas partes de la especificación de MicroProfile OpenAPI a través del mecanismo
MicroProfile
config como sea necesario para la aplicación. La característica mpOpenAPI-1.0 lee los valores configurados cuando se
inicia la aplicación.
- Configure una o varias de las configuraciones básicas que están disponibles
en la especificación de MicroProfile OpenAPI para la aplicación.
- Para añadir valor, la característica mpOpenAPI-1.0 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 uno de los siguientes procedimientos, o una combinación de ellos,
para proporcionar entrada para la generación del documento OpenAPI resultante
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 modelo de OpenAPI.
- Utilice un editor de texto para escribir un documento de OpenAPI estático en formato YAML o JSON, y, a continuación,
coloque el archivo openapi.yaml, openapi.yml o
openapi.json en el directorio META-INF de la
aplicación.
- Especifique anotaciones de MicroProfile OpenAPI
en código Java para aumentar y documentar una aplicación.
- Utilice filtrar
para actualizar el modelo OpenAPI después de que se haya creado utilizando
los mecanismos de documentación.
- Habilite la característica mpOpenAPI-1.0 en la configuración de servidor Liberty.
<server>
<featureManager>
<feature>mpOpenAPI-1.0</feature>
</featureManager>
</server>
- Despliegue la aplicación.
- Opcional: Compruebe los resultados de validación y asegúrese de que la aplicación se ajusta a la
especificación de 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: La validación del documento OpenAPI ha producido el
error o los errores siguientes:
- Mensaje: Falta el campo "ámbitos" necesario o dicho campo se ha establecido en un valor no válido, Ubicación: #/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 API públicas no SSL, vea el documento en
http://host_Liberty:puerto_http/openapi.
- Para API públicas SSL, vea el documento en
https://host_Liberty:puerto_https/openapi.
Resultados
La interfaz de usuario OpenAPI representa la definición de
/openapi
para mostrar una interfaz de usuario en
http://host_Liberty:puerto_http/openapi/ui. Si
habilita SSL, puede acceder a la interfaz de usuario protegida en
https://host_Liberty:puerto_https/openapi/ui.