Vidocq Documentation

Grimm is the MicroProfile OpenAPI 4.1 implementation of the Vidocq ecosystem. It scans the annotations scattered across JAX-RS resources, merges them with an optional static document and an optional OASModelReader, applies OASFilter filters, and publishes a unified OpenAPI 3.1 document on /openapi. Goal: 100 % MicroProfile OpenAPI 4.1 TCK conformance (currently 349/349), zero external dependency, strict JPMS, jlink-ready.

Origin of the name

Jacob (1785-1863) and Wilhelm Grimm (1786-1859), Prussian linguists and philologists. Authors of Kinder- und Hausmärchen (the Fairy Tales) and of the Deutsches Wörterbuch, founders of modern Germanic philology. See the Wikipedia article.

The Grimms gathered scattered oral tradition — tales, legends, word roots — and indexed, classified, and published it as an ordered catalogue. The Wörterbuch set out to record every attested German word with its variants, derivations, and occurrences. Grimm the runtime does exactly that for OpenAPI annotations: it gathers the @Operation, @Parameter, @Schema, @OpenAPIDefinition declarations scattered across the JAX-RS codebase, classifies them by path and HTTP verb, and produces a unified OpenAPI 3.1 document at startup. The folklorist becomes a compiler of API contracts.

The Grimm brothers, philologists Grimm, the OpenAPI runtime

Collecting scattered oral tales

Scanning @Operation, @Parameter, @Schema annotations

Indexing by motif (roots, phonetic variants)

Catalogue keyed by (path, HTTP verb) pairs

Deutsches Wörterbuch — reasoned dictionary

Unified OpenAPI 3.1 document delivered to the client

Critical edition — variants, sources, attestations

Merge of OASModelReader + static file + annotations + filters

Grimm’s Law — phonetic transformation rules

ConfigApplier pipeline — rules driven by mp.openapi.*

Distribution via press and bookshops

GET /openapi endpoint (YAML by default, JSON on request)

At a glance

Implemented spec

MicroProfile OpenAPI 4.1

Repo

https://codeberg.org/Vidocq/grimm

Java

25 (LTS)

JPMS modules

io.vidocq.grimm.core, io.vidocq.grimm.cdi.vauban

Public packages

io.vidocq.grimm.api. (stable SPI), io.vidocq.grimm.cdi. (CDI integration)

Runtime dependencies

microprofile-openapi-api 4.1, jakarta.ws.rs-api 4.0, jakarta.enterprise.cdi-api 4.1, jakarta.annotation-api 3.0, io.vidocq.ravel:ravel-mp-config-api

jlink-ready

✅ — every sub-module ships its own module-info.java, no Automatic-Module-Name fallback.

MP OpenAPI 4.1 TCK

✅ 349 / 349 — see detailed status

Three identifying traits

  1. Zero external dependency beyond Jakarta / MicroProfile specs — no SnakeYAML, no Jackson, no SmallRye. The YAML and JSON serializers are hand-written in grimm-core. The only companion library is Ravel for MicroProfile Config, itself zero-dependency.

  2. Startup resolution, not per request — every annotation is scanned once, when the CDI container starts, by a Vauban Build Compatible Extension. The document is cached in GrimmModelCache and served on every call to /openapi. No per-request recompute, no hot locking.

  3. Strict JPMS — every Grimm artefact has its own module-info.java. Walled packages: io.vidocq.grimm.api. exported, io.vidocq.grimm.internal. hidden, no unjustified opens, no setAccessible(true) in production.

Position in the ecosystem

Diagram

Grimm consumes the ecosystem from the bottom up: Chappe serves the endpoint, Cassini exposes the JAX-RS resource that returns the document, Vauban triggers the BCE that orchestrates the startup scan, Ravel resolves the mp.openapi.* keys. Grimm adds the API catalogue layer — without rewriting anything else.

  • Getting started — first annotated resource, first /openapi call.

  • Usage patterns — pagination, polymorphism, security, servers, callbacks.

  • Concepts — OpenAPI model, scan, merge, filters.

  • Internals — pipeline, threading, Vauban BCE.

  • TCK — execution, status, exclusions.

  • Reference — artefacts, annotations, mp.openapi.* keys.

  • Migration — from SmallRye or Quarkus.

Next: Getting started.