Vidocq Documentation

Grimm est en 0.1.0-SNAPSHOT. La spec MicroProfile OpenAPI 4.1 est entièrement couverte (TCK 349/349, voir état TCK), mais la SPI publique peut encore évoluer avant la 1.0.0. Cette page documente les correspondances de modèle pour préparer une migration progressive.

Côté code applicatif, la migration est triviale : Grimm consomme strictement les annotations standard org.eclipse.microprofile.openapi.annotations.*. Aucun import propriétaire à remplacer. Les écarts portent sur la configuration et le packaging.

Depuis SmallRye OpenAPI

SmallRye OpenAPI est l’implémentation de référence chez Quarkus et certains serveurs Jakarta EE. Migration directe — Grimm vise la stricte conformance à la même spec.

SmallRye OpenAPI Grimm Note

Annotations org.eclipse.microprofile.openapi.annotations.*

Mêmes annotations

Aucun changement de code applicatif.

Scan classpath au démarrage

Scan via BCE Vauban au démarrage

Sémantique identique. Pas de scan par requête dans les deux cas.

Endpoint /openapi

Endpoint /openapi

Identique. Content negotiation YAML/JSON identique.

mp.openapi.* (clés MP Config)

mp.openapi.* (mêmes clés)

Surcharges, exclusions, filtres, model reader : identiques.

Dépendances : Jandex, SnakeYAML, Jackson, etc.

Aucune (sérialiseurs maison)

Empreinte de classpath réduite. Compatibilité jlink immédiate.

quarkus.smallrye-openapi.path

Endpoint /openapi fixe (spec MP)

Pour publier sur un autre chemin, ajouter un alias JAX-RS côté application.

Depuis Quarkus OpenAPI

Quarkus OpenAPI repose sur SmallRye OpenAPI mais ajoute des extensions propriétaires.

Quarkus OpenAPI Grimm Note

Build-time scanning via Jandex

Runtime scanning via BCE Vauban (au démarrage, pas par requête)

Coût équivalent en latence de démarrage. Pas de Jandex index à maintenir.

quarkus.smallrye-openapi.info-*

@OpenAPIDefinition (annotation standard)

Privilégier l’annotation portable.

quarkus.smallrye-openapi.security-scheme

@SecurityScheme (annotation standard)

Privilégier l’annotation portable.

Swagger UI intégré

Hors périmètre Grimm

Brancher Swagger UI ou Redoc côté application comme une ressource statique.

quarkus.dev hot reload

Pas d’équivalent Dev Mode

Le cycle est ./mvnw clean install + redémarrage. Voir Vauban.

Points d’attention

  • Pas de scan classpath à chaud — Grimm n’expose aucun rafraîchissement du document à chaud (la spec MP OpenAPI ne le requiert pas). Toute modification d’annotation suppose un redémarrage.

  • Pas de setAccessible(true) — si du code applicatif utilisait des classes non-publiques avec un ancien scanner permissif, Grimm n’y accédera pas. Ouvrir les packages dans le module-info.java applicatif ou rendre les types public.

  • YAML strict — le sérialiseur YAML maison émet la version 1.2 stricte. Certains clients YAML laxistes (anciens browsers) peuvent réclamer des indentations différentes. Préférer le format JSON dans le doute.

  • mp.openapi.servers — la surcharge remplace entièrement la liste des servers du document (comportement spec). Pour une fusion, passer par un OASFilter.

Checklist de portage

  1. Déclarer grimm-core + grimm-cdi-vauban au lieu de SmallRye / Quarkus OpenAPI.

  2. Vérifier les annotations applicatives : doivent toutes être issues de org.eclipse.microprofile.openapi.annotations.*. Remplacer toute annotation propriétaire.

  3. Migrer les propriétés quarkus.smallrye-openapi. vers @OpenAPIDefinition / @SecurityScheme / @Server ou clés mp.openapi..

  4. Lancer ./mvnw test puis ./run-official-tck-mp-openapi-4.1.sh (voir TCK).

  5. Diff le document produit avant/après — vérifier info, servers, paths, components/schemas.

  6. Brancher Swagger UI ou Redoc côté application si nécessaire.

Pour aller plus loin