Vidocq Documentation

Cette page consolide la surface publique de Grimm : artefacts à déclarer, modules JPMS exportés, annotations OpenAPI 3.1 supportées par le scanner, et clés mp.openapi.* reconnues par ConfigApplier.

Artefacts Maven

groupId artifactId Rôle

io.vidocq.grimm

grimm-core

Scanner d’annotations, sérialiseur JSON/YAML, modèle interne, fusion, OASFactoryResolver.

io.vidocq.grimm

grimm-cdi-vauban

BCE Vauban, GrimmModelCache, ressource JAX-RS /openapi, producer de configuration.

io.vidocq.grimm

grimm-bench

Benchmarks JMH (vs SmallRye). Pas pour la production.

io.vidocq.grimm

grimm-examples

Exemples d’utilisation, autonomes ou intégrés.

io.vidocq.grimm

grimm-tck

Runner officiel TCK MP OpenAPI 4.1 — hors reactor (Model 4.0.0). Ne pas déclarer en dépendance applicative.

Toutes les versions à 0.1.0-SNAPSHOT au moment de la rédaction.

Modules JPMS

Module Contenu

io.vidocq.grimm.core

io.vidocq.grimm.api. (SPI publique), io.vidocq.grimm.internal. (scanner, serializer, merger, model — non exporté).

io.vidocq.grimm.cdi.vauban

io.vidocq.grimm.cdi.* — GrimmExtension, OpenApiResource, GrimmModelCache, GrimmConfigProducer, GrimmAutoDiscovery.

io.vidocq.grimm.internal.* n’est jamais exporté. Toute classe applicative qui en dépend signale une régression à corriger.

Annotations MicroProfile OpenAPI supportées

Annotation Effet Statut

@OpenAPIDefinition

Métadonnées racine (info, tags, servers, security, externalDocs).

✅

@Operation

Décrit une méthode JAX-RS : résumé, description, operationId, deprecated.

✅

@Parameter

Décrit un paramètre (path, query, header, cookie).

✅

@RequestBody

Décrit le corps de requête : contenu, schéma, exemples.

✅

@APIResponse / @APIResponses

Décrit les réponses possibles, code par code, avec headers et liens.

✅

@Schema

Décrit un type : titre, description, contraintes, oneOf, discriminator.

✅

@SecurityScheme / @SecurityRequirement / @SecuritySchemes

Schémas de sécurité (HTTP, API Key, OAuth2, OpenID Connect) et exigences.

✅

@Server / @Servers

URL(s) cible(s) à inscrire sur le document, l’opération ou le chemin.

✅

@Tag / @Tags

Groupage logique des opérations.

✅

@Callback / @Callbacks

Webhooks décrits côté serveur.

✅

@Extension / @Extensions

Extensions x-* libres.

✅

@ExternalDocumentation

Lien vers documentation externe.

✅

@Components

Catalogue de réutilisation explicite.

✅

@Hidden

Masque une classe, une méthode ou un paramètre du document.

✅

Annotations JAX-RS prises en compte par le scanner : @Path, @GET, @POST, @PUT, @DELETE, @PATCH, @HEAD, @OPTIONS, @Produces, @Consumes, @PathParam, @QueryParam, @HeaderParam, @CookieParam, @FormParam, @MatrixParam, @DefaultValue, @ApplicationPath.

Clés MicroProfile Config

Toutes les clés sont lues via ConfigProvider.getConfig(). Voir io.vidocq.grimm.internal.config.ConfigApplier.

Clé Effet

mp.openapi.scan.disable

Booléen. Désactive entièrement le scan d’annotations.

mp.openapi.scan.packages

Liste de packages à scanner (whitelist, comma-separated).

mp.openapi.scan.classes

Liste de classes à scanner (whitelist).

mp.openapi.scan.exclude.packages

Liste de packages exclus.

mp.openapi.scan.exclude.classes

Liste de classes exclues.

mp.openapi.scan.beanvalidation

Booléen. Active la dérivation de contraintes Bean Validation vers le schéma.

mp.openapi.filter

FQCN d’un OASFilter à appliquer après fusion.

mp.openapi.model.reader

FQCN d’un OASModelReader invoqué avant la fusion.

mp.openapi.servers

Liste d’URL de serveurs (remplace servers du document).

mp.openapi.servers.path.<path>

Surcharge servers pour un chemin précis.

mp.openapi.servers.operation.<operationId>

Surcharge servers pour une opération précise.

mp.openapi.schema.<FQCN>

Snippet JSON décrivant un schéma pour la classe donnée (override total).

mp.openapi.extensions.scan.disable

Booléen. Désactive le scan des annotations @Extension.

Les clés mp.openapi.application.path.disable et mp.openapi.extensions.path mentionnées par la spec peuvent être ajoutées à la liste blanche du ConfigApplier sans modification de la SPI publique. Vérifier le statut courant dans ConfigApplier.java.

Endpoint /openapi

Chemin

/openapi

Verbe

GET

Types

application/yaml (défaut, spec §2.2), application/json

Override de format

?format=yaml, ?format=yml, ?format=json (prioritaire sur Accept, spec §2.3)

Source

GrimmModelCache.getDocument()

Statut

Toujours 200 quand le scan a abouti

Compatibilité

  • Java 25 (LTS), Maven 3.9.16.

  • JAX-RS 4.0 (Cassini ou autre runtime conforme).

  • CDI 4.1 Lite (Vauban) ou Lite-compatible.

  • Pas de dépendance Jakarta EE Full Profile.

Bugs et benchmarks

  • BUG.md — bugs reproductibles tracés (à créer si absent).

  • BENCH.md — benchmarks JMH (à créer si absent).

Pour aller plus loin