[18.0.0.1 and later]

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

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

  1. 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
  2. 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.
  3. Habilite la característica mpOpenAPI-1.0 en la configuración de servidor Liberty.
    <server>
       <featureManager>
          <feature>mpOpenAPI-1.0</feature>
       </featureManager>
    </server>
  4. Despliegue la aplicación.
  5. 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
  6. 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.

Icono que indica el tipo de tema Tema de tarea

Nombre de archivo: twlp_mpopenapi.html