GuicedEE REST Skill | Agent Skills

GuicedEE REST

Lightweight Jakarta REST (JAX-RS) adapter for Vert.x 5 with full GuicedEE integration.

Core Concept

Annotate your classes with standard @Path, @GET, @POST, etc. — routes are discovered at startup via ClassGraph and registered on the Vert.x Router automatically. Resource instances are created through Guice, so @Inject works everywhere.

Required Flow

Add com.guicedee:rest dependency (pulls in web transitively).

Configure module-info.java:

module my.app {
    requires com.guicedee.rest;
    opens my.app.resources to com.google.guice, com.guicedee.rest;
    opens my.app.dto to tools.jackson.databind;
}

Create resource classes with Jakarta REST annotations:

@Path("/users")
public class UserResource {
    @Inject
    private UserService userService;

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Uni<List<User>> listUsers() {
        return userService.findAll();
    }

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public Uni<User> createUser(CreateUserRequest request) {
        return userService.create(request);
    }

    @GET
    @Path("/{id}")
    public Uni<User> getUser(@PathParam("id") Long id) {
        return userService.findById(id);
    }
}

Bootstrap GuicedEE — routes are registered automatically:

IGuiceContext.registerModuleForScanning.add("my.app");
IGuiceContext.instance().getConfig()
    .setClasspathScanning(true).setAnnotationScanning(true)
    .setMethodInfo(true).setFieldInfo(true);
IGuiceContext.instance().inject();

Observe getLoadingFinished() before probing routes. Executable mains can use GuiceApplication.run(...) from inject to own startup failure and process exit.

Supported Annotations

HTTP Methods

@GET, @POST, @PUT, @DELETE, @PATCH, @HEAD, @OPTIONS

Parameter Binding

@PathParam, @QueryParam, @HeaderParam, @CookieParam, @FormParam, @MatrixParam, @BeanParam

Content Negotiation

@Produces, @Consumes

Startup Flow

IGuiceContext.instance().inject()
 └─ OperationRegistry scans for @Path-annotated classes via ClassGraph
 └─ Routes mapped to Vert.x Router
 └─ Resource instances obtained from Guice injector

Return Types

Methods can return:

Plain objects (serialized to JSON via the GuicedEE Jackson 3 DefaultObjectMapper)
Uni<T> for reactive composition
Future<T> for Vert.x futures
void for fire-and-forget operations

Response bodies are serialized by ResponseHandler using the shared DefaultObjectMapper (tools.jackson.databind), not Vert.x's built-in codec. Jackson annotations remain on com.fasterxml.jackson.annotation (2.x), so @JsonProperty, @JsonInclude, @JsonAutoDetect, @JsonIdentityInfo, and reference annotations work unchanged.

Automatic telemetry

When com.guicedee.telemetry is present, the REST router automatically creates a SERVER span for each endpoint, extracts W3C request context, keeps the span current across the reactive Uni subscription, and ends it when the HTTP response completes. Endpoint authors do not need to add @Trace for the HTTP boundary. Resource and service methods may still use @Trace for separate internal spans.

Non-Negotiable Constraints

Resource classes must be in packages opened to com.google.guice and com.guicedee.rest.
DTO packages must opens to tools.jackson.databind.
Module must requires com.guicedee.rest;.
The web module is included transitively — do not create HttpServer manually.
SPI implementations must be dual-registered (module-info.java + META-INF/services/).

Agent Skills: GuicedEE REST

Install this agent skill to your local

Skill Files