Génération OpenAPI

Statut documentaire : architecture — voir Maturité et preuves.

OpenAPI est une projection documentaire des services HTTP publiés. Le document généré doit refléter le contrat public réellement exposé et ne pas révéler de types ou noms d'implémentation privés.

Source de vérité

La chaîne recommandée est :

published model capability
    -> HTTP service contract
    -> route/schema metadata
    -> OpenAPI document

Le document OpenAPI est donc dérivé du contrat de publication ; il ne doit pas devenir la source primaire du modèle métier.

Exigences

Une génération fiable doit conserver :

• noms publics ;
• types de paramètres et retours ;
• nullabilité ;
• tableaux et objets publiés ;
• erreurs documentables ;
• exigences de sécurité ;
• version du contrat ;
• semantics async/job lorsque pertinentes.

Une signature non projetable doit provoquer un diagnostic explicite plutôt qu'une description OpenAPI approximative.