Swagger / OpenAPI

L'API expose une documentation OpenAPI (Swagger) générée à partir des contrôleurs et des schémas de la couche web/.

Accès

Le Swagger est servi sur /docs (configuré dans web/swagger.ts).

Exposition conditionnelle + Basic Auth

Le Swagger n'est monté que si SWAGGER_USER et SWAGGER_PASSWORD sont tous deux définis. Si l'un manque, les docs ne sont pas montées du tout. L'accès à /docs, /docs-json et /docs-yaml est protégé par HTTP Basic Auth avec ces identifiants.

URL	Contenu
/docs	UI Swagger interactive
/docs-json	Document OpenAPI au format JSON
/docs-yaml	Document OpenAPI au format YAML

Variables associées (voir Installation) :

SWAGGER_USER=
SWAGGER_PASSWORD=
SWAGGER_TITLE=Ikloze API     # titre du document (défaut : Ikloze API)

Comment c'est généré

Les schémas Swagger/DTO vivent dans la couche web/<module>/ (décorateurs Nest), séparés des schémas Zod de validation de la couche app/. La couche web/ est volontairement mince : elle décrit le contrat HTTP, tandis que la logique et la validation métier vivent dans les services. Voir Architecture › Vue d'ensemble.

Référence d'API auto-générée — hors périmètre

Intégrer le rendu de l'OpenAPI dans ce site (page de référence statique générée depuis /docs-json) est une amélioration possible mais hors périmètre actuel. Aujourd'hui, la référence interactive reste le Swagger live sur /docs.