guicedee/guicedee-openapi

GuicedEE OpenAPI

Automatic OpenAPI 3.1 spec generation and serving for the GuicedEE / Vert.x stack.

Core Concept

Add the dependency, annotate your Jakarta REST resources with Swagger/OpenAPI annotations, and the module scans them at startup — /openapi.json and /openapi.yaml are live with zero configuration.

Required Flow

1. Add com.guicedee:openapi dependency.
2. Annotate REST resources with Swagger/OpenAPI annotations:

   @Path("/users")
   @Tag(name = "Users", description = "User management operations")
   public class UserResource {
   
       @GET
       @Operation(summary = "List all users")
       @APIResponse(responseCode = "200", description = "Success",
           content = @Content(schema = @Schema(implementation = User.class)))
       public List<User> listUsers() { ... }
   
       @POST
       @Operation(summary = "Create a new user")
       public User createUser(CreateUserRequest request) { ... }
   }
   

3. Configure module-info.java:

   module my.app {
       requires com.guicedee.openapi;
   }
   

4. Bootstrap GuicedEE — OpenAPI endpoints are live automatically:

   IGuiceContext.registerModuleForScanning.add("my.app");
   IGuiceContext.instance().inject();
   // GET /openapi.json → OpenAPI 3.1 JSON spec
   // GET /openapi.yaml → OpenAPI 3.1 YAML spec
   

Companion: Swagger UI

Add the guiced-swagger-ui module for a browsable UI at /swagger/:

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

The UI reads from /openapi.json automatically — zero code required.

Supported Annotations

All standard Swagger/OpenAPI annotations are supported:

• @OpenAPIDefinition — API-level info, servers, security
• @Tag — resource grouping
• @Operation — per-endpoint summary, description
• @APIResponse / @APIResponses — response documentation
• @Parameter — parameter documentation
• @Schema — model schema customization
• @Content — response content types
• @RequestBody — request body documentation

Non-Negotiable Constraints

• Module must requires com.guicedee.openapi;.
• Requires rest module for Jakarta REST resource scanning.
• The OpenAPI module is registered automatically — no provides needed.
• Spec generation happens at startup via ClassGraph scanning.