# Documentation OpenAPI / Swagger

RH Connect expose sa spécification OpenAPI 3.0 et une interface Swagger UI interactive.

L'inventaire actuel contient **94 chemins** et **159 opérations**, documentation comprise.

## Activation en développement

Ajouter dans le fichier `.env` :

```dotenv
SWAGGER_ENABLED=true
OPENAPI_SERVER_URL=http://localhost:8000
```

Le service `backend` de `docker-compose.yml` doit transmettre ces variables :

```yaml
SWAGGER_ENABLED: ${SWAGGER_ENABLED:-false}
OPENAPI_SERVER_URL: ${OPENAPI_SERVER_URL:-http://localhost:8000}
```

Après reconstruction du backend :

```powershell
docker compose up -d --build backend
```

- Interface : <http://localhost:8000/api-docs>
- Spécification JSON : <http://localhost:8000/api/openapi>

## Authentification

La connexion locale `POST /api/auth/login` renvoie un JWT. Dans Swagger UI, utiliser le bouton **Authorize**, puis renseigner uniquement le jeton dans `bearerAuth`. Swagger ajoute automatiquement le préfixe `Bearer`.

La session SSO par cookie est également décrite sous `cookieAuth`. La route interne du planificateur utilise `cronSecret` (`x-cron-secret`).

## Régénération de l’inventaire

Après l’ajout ou la suppression d’un handler `src/app/api/**/route.ts` :

```powershell
node scripts/generate-openapi-routes.mjs
```

Le script maintient `src/lib/openapi-routes.generated.ts`. Les schémas et particularités métier restent définis dans `src/lib/swagger.ts`.

## Production

Conserver `SWAGGER_ENABLED=false`. Lorsque la documentation devra être publiée, elle devra être activée explicitement et protégée selon les règles d’accès de l’infrastructure.