GuicedEE Swagger UI

Browsable Swagger UI for the GuicedEE / Vert.x stack. Add the dependency and a fully functional Swagger UI is mounted at /swagger/ automatically — it reads from your /openapi.json endpoint out of the box, with zero code required.

Built on Swagger UI · Vert.x 5 · Google Guice · JPMS module com.guicedee.swaggerui · Java 25+

📦 Installation

<dependency>
  <groupId>com.guicedee</groupId>
  <artifactId>guiced-swagger-ui</artifactId>
</dependency>

Gradle (Kotlin DSL)

implementation("com.guicedee:guiced-swagger-ui:2.0.0-SNAPSHOT")

OpenAPI spec generation — pair this module with the openapi module for automatic spec generation:

<dependency>
  <groupId>com.guicedee</groupId>
  <artifactId>openapi</artifactId>
</dependency>

✨ Features

• Zero-config UI mounting — SwaggerUIRegistration registers a Vert.x StaticHandler on the router at startup; Swagger UI is live immediately
• Pre-bundled assets — all Swagger UI static resources (HTML, JS, CSS, favicons) are included in the JAR under swagger/
• Points at /openapi.json by default — the bundled swagger-initializer.js is pre-configured to load the spec from /openapi.json
• Fully configurable — route path, resource root, caching, directory listing, and index page are all controllable via system properties or environment variables
• Can be disabled — set guicedee.swaggerui.enabled=false to skip registration entirely (e.g. in production)
• JPMS + ServiceLoader friendly — fully modular with module-info.java and META-INF/services descriptors

🚀 Quick Start

Step 1 — Add both dependencies (see Installation).

Step 2 — Bootstrap GuicedEE:

IGuiceContext.instance().inject();

Step 3 — Open your browser:

http://localhost:8080/swagger/

That's it. The Swagger UI loads and reads from /openapi.json automatically. If the openapi module is on the classpath your Jakarta REST resources appear in the UI immediately.

📐 Architecture

Startup
  IGuiceContext.instance()
   └─ SwaggerUIRegistration            (VertxRouterConfigurator, order MAX_VALUE-100)
       └─ Reads configuration from system properties / environment
       └─ Creates StaticHandler for classpath "swagger" directory
       └─ Mounts route on Router at /swagger/* (configurable)

Request lifecycle

HTTP GET /swagger/index.html
 → Vert.x Router
   → StaticHandler
     → Serves index.html from classpath:swagger/
       → Browser loads swagger-ui-bundle.js, CSS, etc.
       → swagger-initializer.js → fetch(/openapi.json)
       → Swagger UI renders the API documentation

Bundled assets

The following Swagger UI files are bundled in the JAR at src/main/resources/swagger/:

File	Purpose
index.html	Entry point HTML page
swagger-initializer.js	Configures SwaggerUIBundle (points at /openapi.json)
swagger-ui-bundle.js	Core Swagger UI JavaScript
swagger-ui-standalone-preset.js	Standalone layout preset
swagger-ui.css / index.css	Stylesheets
favicon-16x16.png / favicon-32x32.png	Favicons
oauth2-redirect.html	OAuth 2 redirect handler

⚙️ Configuration

All configuration is driven by system properties with automatic environment variable fallbacks (via Environment.getSystemPropertyOrEnvironment).

Property	Default	Purpose
guicedee.swaggerui.enabled	true	Enable or disable Swagger UI registration
guicedee.swaggerui.route	/swagger/*	The Vert.x route path for the UI
guicedee.swaggerui.resourceRoot	swagger	Classpath directory containing the UI assets
guicedee.swaggerui.filesReadOnly	true	Whether the static handler treats files as read-only
guicedee.swaggerui.cache.enabled	true	Enable HTTP caching headers
guicedee.swaggerui.cache.maxAgeSeconds	86400 (24h)	Cache-Control: max-age value in seconds
guicedee.swaggerui.directoryListing	false	Whether to allow directory listing
guicedee.swaggerui.indexPage	index.html	The default index page to serve

Examples

Disable Swagger UI in production:

java -Dguicedee.swaggerui.enabled=false -jar myapp.jar

Or via environment variable:

export GUICEDEE_SWAGGERUI_ENABLED=false

Change the mount path:

java -Dguicedee.swaggerui.route=/api-docs/* -jar myapp.jar

Disable caching during development:

java -Dguicedee.swaggerui.cache.enabled=false -jar myapp.jar

Customizing the OpenAPI URL

The bundled swagger-initializer.js points at /openapi.json by default:

window.ui = SwaggerUIBundle({
    url: "/openapi.json",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset
    ],
    plugins: [
        SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
});

To point at a different spec URL, replace swagger-initializer.js in your project's src/main/resources/swagger/ directory — your copy will take precedence over the JAR's bundled version.

🔌 SPI & Extension Points

SPI	Purpose
VertxRouterConfigurator	Provided by SwaggerUIRegistration — mounts the static handler on the router

The module also ships an empty META-INF/services/com.guicedee.guicedservlets.openapi.services.IGuicedSwaggerConfiguration file, allowing the OpenAPI module to discover it as a potential contributor.

🗺️ Module Graph

com.guicedee.swaggerui
 └── com.guicedee.vertx.web           (Vert.x Web + Router SPI)

The module is intentionally lightweight — it depends only on com.guicedee.vertx.web for the Router and StaticHandler types.

🧩 JPMS

Module name: com.guicedee.swaggerui

The module:

• Is declared open (all packages are reflectively accessible)
• requires com.guicedee.vertx.web
• provides VertxRouterConfigurator with SwaggerUIRegistration

🏗️ Key Classes

Class	Package	Role
SwaggerUIRegistration	com.guicedee.servlets.swaggerui	VertxRouterConfigurator (sort order MAX_VALUE - 100) — reads configuration, creates a StaticHandler, and mounts it on the router

Route normalization

SwaggerUIRegistration normalizes the configured route to ensure it:

1. Starts with /
2. Ends with /* (required by Vert.x StaticHandler)

For example: swagger → /swagger/*, /api-docs/ → /api-docs/*

🧪 Testing

The test suite bootstraps GuicedEE, starts the Vert.x HTTP server, and verifies the Swagger UI is served:

IGuiceContext.instance().inject();

HttpClient client = HttpClient.newBuilder()
    .connectTimeout(Duration.of(5, ChronoUnit.SECONDS))
    .build();

HttpResponse response = client.send(
    HttpRequest.newBuilder()
        .GET()
        .uri(new URI("http://localhost:8080/swagger/index.html"))
        .build(),
    HttpResponse.BodyHandlers.discarding());

assertEquals(200, response.statusCode());

Run tests:

mvn test

🤝 Contributing

Issues and pull requests are welcome — please add tests for new configuration options or UI customizations.

📄 License

Apache 2.0