Documentación Openapi en Quarkus (Swagger y Rapidoc)

1️⃣ Agregar la extensión OpenAPI

Quarkus usa SmallRye OpenAPI para generar documentación OpenAPI 3 automáticamente desde tus endpoints REST.

# Windows
.\gradlew.bat addExtension --extensions="smallrye-openapi"

# Linux/macOS
./gradlew addExtension --extensions="smallrye-openapi"

Qué hace este comando:

Descarga la dependencia smallrye-openapi.
Configura Quarkus para generar /q/openapi.
Permite usar Swagger UI y otros visualizadores sin tocar el backend.

2️⃣ Crear un endpoint de ejemplo con etiquetas para OpenAPI

Archivo: src/main/java/py/com/jsifen/HelloResource.java

package py.com.jsifen;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import org.eclipse.microprofile.openapi.annotations.Operation;
import org.eclipse.microprofile.openapi.annotations.tags.Tag;

@Path("/hello")
@Tag(name = "Hello", description = "Endpoint de prueba Hello")
public class HelloResource {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    @Operation(
        summary = "Saludo simple",
        description = "Devuelve un saludo de prueba"
    )
    public String hello() {
        return "Hello from Quarkus!";
    }
}

Qué hace este código:

@Path("/hello") define el endpoint REST.
@Tag agrega metadata para que la UI de documentación (Swagger/RapiDoc) agrupe y describa el endpoint.
@Operation proporciona un resumen y descripción que aparece en la documentación.
Devuelve un saludo de texto plano.

3️⃣ Levantar Quarkus Dev y probar Swagger UI

# Windows
.\gradlew.bat quarkusDev

# Linux/macOS
./gradlew quarkusDev

OpenAPI JSON: http://localhost:8080/q/openapi
Swagger UI: http://localhost:8080/q/swagger-ui

Si querés cambiar el puerto y el path de Swagger UI, agregá estas líneas en application.properties:

quarkus.http.port=8000
quarkus.swagger-ui.path=/doc/swagger

Luego, al levantar Quarkus Dev, Swagger UI estará en el nuevo path y puerto:

OpenAPI JSON: http://localhost:8000/q/openapi
Swagger UI: http://localhost:8000/doc/swagger

4️⃣ Crear la carpeta para recursos estáticos (si no existe)

Si querés usar Redoc o RapiDoc, necesitás la carpeta:

src/main/resources/META-INF/resources/

Si no existe, creala manualmente dentro de src/main/resources.
Todo lo que pongas en esta carpeta se servirá automáticamente desde el root (/) del servidor Quarkus.

5️⃣ Agregar RapiDoc

Archivo mínimo rapidoc.html:

src/main/resources/META-INF/resources/rapidoc.html

<!DOCTYPE html>
<html>
  <head>
    <title>API Docs RapiDoc</title>
    <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
  </head>
  <body>
    <rapi-doc 
      spec-url="/q/openapi"
      render-style="focused"
      theme="light">
    </rapi-doc>
  </body>
</html>

Subcarpeta opcional:

src/main/resources/META-INF/resources/doc/rapidoc/index.html

URL según ubicación:

Ubicación del archivo	URL para abrirlo
META-INF/resources/rapidoc.html	http://localhost:8080/rapidoc.html
META-INF/resources/doc/rapidoc/index.html	http://localhost:8080/doc/rapidoc/index.html

❌ Evitar ponerlo directamente en src/main/resources/ sin META-INF/resources/ → causará 404.

6️⃣ Levantar y probar

# Windows
.\gradlew.bat quarkusDev

# Linux/macOS
./gradlew quarkusDev

Abrir en navegador según el archivo que tengas:
http://localhost:8080/rapidoc.html
http://localhost:8080/doc/rapidoc/index.html

7️⃣ Resumen de rutas y visualizadores

Feature	Ruta	Visualizador
OpenAPI JSON	/q/openapi	estándar OpenAPI 3
Swagger UI	/q/swagger-ui	oficial SmallRye
RapiDoc	/rapidoc.html	alternativa moderna
RapiDoc subcarpeta	/doc/rapidoc/index.html	alternativa moderna

💡 Tips finales

Reiniciá Quarkus Dev cada vez que agregues nuevos archivos estáticos.
Subcarpetas dentro de META-INF/resources son totalmente soportadas.
Todo sigue cumpliendo OpenAPI 3, así que podés cambiar la UI sin afectar el estándar.

Anotador de Informatica

Buscar este blog