Vidocq Documentation

Grimm met en œuvre la spec MicroProfile OpenAPI 4.1, qui s’appuie elle-même sur OpenAPI 3.1.0. Cette page explique le vocabulaire — Components, Paths, Operations, Schemas — et la mécanique de fusion entre les différentes sources de modèle.

Le modèle OpenAPI 3.1

Le format OpenAPI décrit un service HTTP par un arbre JSON ou YAML structuré. Trois niveaux principaux :

Niveau Rôle

info

Métadonnées du contrat : titre, version, licence, contact, description.

paths

Catalogue des opérations. Chaque clé est un chemin (/pets/{id}), chaque valeur regroupe les verbes HTTP (get, post, etc.) et leurs Operation.

components

Catalogue de réutilisation : schemas, parameters, responses, requestBodies, headers, securitySchemes, links, callbacks, examples.

Le modèle Java de la spec MP OpenAPI 4.1 reflète cette structure : interface OpenAPI → Info, Paths, Components. Grimm fournit des implémentations concrètes (records ou classes finales) dans io.vidocq.grimm.internal.model, instanciées par sa propre OASFactoryResolver.

Trois sources, une fusion

La spec MP OpenAPI 4.1 §3 prescrit trois sources de modèle, fusionnées dans cet ordre :

  1. Fichier statique — META-INF/openapi.yaml, .yml ou .json packagé dans le classpath. Lu par StaticFileReader. Représente le « squelette éditorial » fourni par l’équipe de design.

  2. OASModelReader — classe applicative implémentant org.eclipse.microprofile.openapi.OASModelReader, désignée par mp.openapi.model.reader. Permet de construire un OpenAPI programmatique.

  3. Scan d’annotations — visite des classes @Path, @OpenAPIDefinition, @Server, @Tag, @SecurityScheme du module CDI courant. Effectuée par AnnotationScanner.

ModelMerger combine les trois — les annotations gagnent sur les conflits, conformément à la spec. Le résultat est un OpenAPI unique, déposé dans GrimmModelCache.

Filtres OASFilter

Une classe applicative implémentant org.eclipse.microprofile.openapi.OASFilter peut transformer le document après fusion, opération par opération. Activation via mp.openapi.filter=fqn.MonFiltre. Grimm invoque le filtre dans FilterInvoker, en un seul passage descendant qui dispatche sur les types Operation, PathItem, APIResponse, Schema, Parameter, etc.

Le filtre est exécuté une fois, à la construction du document, pas par requête. Il n’a donc pas accès à HttpHeaders ou à un contexte de sécurité — pour de la transformation par appel, utiliser un ContainerResponseFilter JAX-RS.

Configuration via MicroProfile Config

La spec MP OpenAPI 4.1 §4 définit un ensemble de clés mp.openapi.* lues via MicroProfile Config — fournies par Ravel dans l’écosystème Vidocq.

Clé Effet

mp.openapi.scan.disable

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

mp.openapi.scan.packages

Liste blanche de packages à scanner (comma-separated).

mp.openapi.scan.classes

Liste blanche de classes spécifiques.

mp.openapi.scan.exclude.packages

Packages exclus du scan.

mp.openapi.scan.exclude.classes

Classes exclues.

mp.openapi.model.reader

FQCN du OASModelReader.

mp.openapi.filter

FQCN du OASFilter.

mp.openapi.servers

Liste d’URL de serveurs à imposer sur le document.

mp.openapi.schema.<FQCN>

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

Voir Référence pour la liste exhaustive et les variantes servers.path. / servers.operation..

Différences avec OpenAPI 3.0 (rappel)

OpenAPI 3.1 (servi par MP OpenAPI 4.1) introduit l’alignement complet avec JSON Schema 2020-12 : type peut être un tableau (["string", "null"]), nullable est remplacé par cette syntaxe, examples est un tableau, webhooks est ajouté à la racine. Grimm reflète ces choix dans son sérialiseur.

Pour aller plus loin