Vidocq Documentation

Grimm est l’implémentation MicroProfile OpenAPI 4.1 de l’écosystème Vidocq. Elle scrute les annotations dispersées dans les ressources JAX-RS, fusionne le résultat avec un éventuel document statique et un éventuel OASModelReader, applique les filtres OASFilter, et publie un document OpenAPI 3.1 unifié sur /openapi. Objectif : conformance 100 % au TCK MicroProfile OpenAPI 4.1 (actuellement 349/349), zéro dépendance externe, JPMS strict, prête pour jlink.

Origine du nom

Jacob (1785-1863) et Wilhelm Grimm (1786-1859), linguistes et philologues prussiens. Auteurs des Kinder- und Hausmärchen (les Contes), du Deutsches Wörterbuch, et fondateurs de la philologie germanique moderne. Voir la fiche Wikipédia.

Les Grimm ont collecté la tradition orale dispersée — contes, légendes, racines de mots — et l’ont indexée, classifiée, publiée en catalogue ordonné. Le Wörterbuch a entrepris de répertorier chaque mot allemand attesté, avec ses variantes, ses dérivés et ses occurrences. Grimm le runtime fait exactement ça pour les annotations OpenAPI : il collecte les @Operation, @Parameter, @Schema, @OpenAPIDefinition dispersés dans tout le code JAX-RS, les classifie par chemin et par verbe HTTP, et produit un document OpenAPI 3.1 unifié au démarrage. Le folkloriste devient compilateur de contrats d’API.

Les frères Grimm, philologues Grimm, le runtime OpenAPI

Collecte de contes oraux dispersés

Scan des annotations @Operation, @Parameter, @Schema

Indexation par motif (racines, variantes phonétiques)

Catalogue par couple (path, verbe HTTP)

Deutsches Wörterbuch — dictionnaire raisonné

Document OpenAPI 3.1 unifié, livré au navigateur

Édition critique — variantes, sources, attestations

Fusion OASModelReader + statique + annotations + filtres

Loi de Grimm — règles de transformation phonétique

Pipeline ConfigApplier — règles de mp.openapi.*

Diffusion en presse, librairie

Endpoint GET /openapi (YAML par défaut, JSON sur demande)

En un coup d’œil

Spec implémentée

MicroProfile OpenAPI 4.1

Dépôt

https://codeberg.org/Vidocq/grimm

Java

25 (LTS)

Modules JPMS

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

Packages publics

io.vidocq.grimm.api. (SPI stable), io.vidocq.grimm.cdi. (intégration CDI)

Dépendances runtime

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

Prête pour jlink

✅ — chaque sous-module a son module-info.java, pas de fallback Automatic-Module-Name.

TCK MP OpenAPI 4.1

✅ 349 / 349 — voir état détaillé

Trois traits identitaires

  1. Zéro dépendance externe au-delà des specs Jakarta / MicroProfile — pas de SnakeYAML, pas de Jackson, pas de SmallRye. Le sérialiseur YAML et le sérialiseur JSON sont écrits à la main dans grimm-core. La seule librairie compagnonne est Ravel pour MicroProfile Config, et elle est elle-même zéro-dépendance.

  2. Résolution au démarrage, pas par requête — toutes les annotations sont scannées une seule fois, à l’activation du container CDI, par une Build Compatible Extension Vauban. Le document est mis en cache (GrimmModelCache) et servi à chaque appel sur /openapi. Aucun recalcul par requête, aucun verrouillage à chaud.

  3. JPMS strict — chaque artefact Grimm a son module-info.java. Packages cloisonnés : io.vidocq.grimm.api. exporté, io.vidocq.grimm.internal. interne, pas de opens non justifié, pas de setAccessible(true) en production.

Positionnement dans l’écosystème

Diagram

Grimm consomme l’écosystème de bas en haut : Chappe sert l’endpoint, Cassini expose la ressource JAX-RS qui renvoie le document, Vauban déclenche la BCE qui orchestre le scan au démarrage, Ravel résout les clés mp.openapi.*. Grimm ajoute la couche de catalogue d’API — sans rien réécrire ailleurs.

Ressources rapides

Suivant : Démarrage rapide.