JavaEE + OpenAPI: Sin MicroProfile

En este artículo les comentaré respecto a los pasos que tuve que seguir para poder emplear OpenAPI en un proyecto JavaEE sin soporte para MicroProfile.

La primera pregunta sería: ¿porqué? La respuesta radica en que para un proyecto deseaba poder generar la documentación de un grupo de microservicios de manera automatizada y sin tener que crear manualmente los archivos de OpenAPI. Pero el servidor de aplicaciones a usar es WebLogic 12c y este no posee soporte de MicroProfile.

Dicho lo anterior, se deben hacer dos pasos para lograr el objetivo que perseguía.

Paso 1. Dependencias

El primer paso fue agregar las dependencias necesarias para poder emplear las anotaciones que necesito para generar la documentación de OpenAPI. Estas son:

<dependency>
    <groupId>org.eclipse.microprofile.openapi</groupId>
    <artifactId>microprofile-openapi-api</artifactId>
    <version>1.1.2</version>
     <scope>provided</scope>
</dependency>
<dependency>
    <groupId>org.apache.geronimo</groupId>
    <artifactId>geronimo-openapi-impl</artifactId>
    <version>1.0.11</version>
     <scope>provided</scope>
</dependency>

Debe observarse que explícitamente indico que el scope es provided. La justificación viene dada porque no deseo agregar todos los jars de OpenAPI ni de Apache Geronimo a mi proyecto, pues de hacerlo WebLogic reportaría una excepción al tratar de hacer el despliegue de este microservicio. Recordemos que WebLogic es sólo un servidor que cumple con la especificación de JEE 7.

Al agregar estas dependencias ya podemos comenzar a hacer uso de las anotaciones de OpenAPI y así comenzar a documentar nuestros servicios.

Paso 2. Plugin de Maven

El siguiente paso es agregar un plugin de Maven para poder generar el json con nuestra documentación. En mi caso seleccione el siguiente:

<plugin>
    <groupId>org.apache.geronimo</groupId>
    <artifactId>geronimo-openapi-maven-plugin</artifactId>
    <version>1.0.11</version>
    <executions>
        <execution>
            <id>generate-openapi.json</id>
            <goals>
                <goal>openapi.json</goal>
            </goals>
            <configuration>
                <application>dev.gerardo.JAXRSConfiguration</application>
                <endpointClasses>
                    <endpointClass>dev.gerardo.api.boundary.MyResource</endpointClass>          
                </endpointClasses>
            </configuration>
        </execution>
    </executions>
</plugin>   

De resaltar que se debe indicar lo siguiente:

• El nombre del archivo que se generará con nuestra documentación, por ejemplo: openapi.json.
• La clase que contiene nuestro JAXRSConfiguration.
• El conjunto de endpoints o microservicios que tenemos definido en nuestro proyecto.

Con esos dos pasos, ya somos capaces de generar la documentación que necesitamos y así poder cumplir con el objetivo que necesitaba.

Conclusión

En este artículo expongo un camino para poder generar documentación de OpenAPI en nuestros microservicios, aunque estos no vayan a ejecutarse en una plataforma de MicroProfile.