# OpenAPI

Sovrium décrit son API HTTP sous forme de documents **OpenAPI 3.1** standard, générés à partir des mêmes schémas Zod de requête/réponse (`src/domain/models/api/`) qui valident le trafic en direct. Parce que les documents OpenAPI exposent la forme complète de l'API, ils sont servis **uniquement aux administrateurs** à l'exécution — jamais aux appelants non authentifiés ou non administrateurs.

:::callout
**Réservé aux administrateurs par conception.** Exposer le schéma de l'API au public divulguerait la surface interne. Sovrium protège tous les endpoints OpenAPI derrière le rôle `admin`. Lorsque `app.auth` n'est pas configuré, les endpoints ne sont pas enregistrés du tout (chaque chemin retourne 404).
:::

## Ce qui est généré

Deux documents OpenAPI plus un explorateur interactif, servis par une instance Sovrium en cours d'exécution.

| Endpoint                     | Retourne         | Description                                            |
| ---------------------------- | ---------------- | ------------------------------------------------------ |
| `GET /api/openapi.json`      | OpenAPI 3.1 JSON | L'API de l'application (tables, enregistrements, etc.) |
| `GET /api/auth/openapi.json` | OpenAPI 3.1 JSON | La surface de l'API Better Auth                        |
| `GET /api/scalar`            | HTML (UI Scalar) | Explorateur interactif unifié pour les deux            |

Le document de l'application est produit par un assistant interne `getOpenAPIDocument(app)` ; le document d'authentification est généré par `generateOpenAPISchema()` de Better Auth. L'UI Scalar monte les deux comme sources commutables (« API » et « Auth »).

## Contrôle d'accès

Les trois endpoints partagent une seule garde administrateur.

| Appelant                             | `/api/openapi.json` | Raison                                                                 |
| ------------------------------------ | ------------------- | ---------------------------------------------------------------------- |
| Non authentifié                      | `401 UNAUTHORIZED`  | Pas de session (sémantique HTTP d'authentification standard)           |
| Authentifié, non administrateur      | `404 NOT_FOUND`     | Anti-énumération : le refus d'autorisation ressemble à « introuvable » |
| Administrateur authentifié           | `200` + document    | Accès complet                                                          |
| Tout appelant, `app.auth` non défini | `404 NOT_FOUND`     | Routes jamais enregistrées                                             |

Les enveloppes 401/404 suivent le [contrat d'erreur canonique](/fr/docs/api-reference#error-response-contract).

## Récupérer les documents

Depuis une instance en cours d'exécution, un administrateur peut récupérer les documents bruts (cookie de session ou en-tête `Authorization: Bearer <token>` requis) :

```bash
# Application API schema
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/api/openapi.json

# Better Auth API schema
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/api/auth/openapi.json
```

Enregistrez un document sur le disque pour l'alimenter vers des outils externes :

```bash
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/api/openapi.json -o app.openapi.json
```

:::callout
**Servi à l'exécution, récupéré par un administrateur.** Les documents OpenAPI sont générés et servis par le serveur en cours d'exécution aux routes réservées aux administrateurs ci-dessus. Pour produire un fichier statique, récupérez la route en tant qu'administrateur et redirigez vers un fichier (illustré ci-dessus). Il n'existe pas de sous-commande CLI `sovrium openapi`. Le schéma JSON, en revanche, _dispose_ d'une commande dédiée — consultez [`sovrium schema`](/fr/docs/json-schema#generating-the-schema).
:::

## Explorateur d'API Scalar

Visitez `/api/scalar` dans un navigateur tout en étant connecté en tant qu'administrateur pour parcourir, rechercher et tester chaque endpoint. L'explorateur affiche à la fois les documents de l'application et de Better Auth depuis une seule page.

```
http://localhost:3000/api/scalar
```

Il expose les schémas de requête/réponse, les codes de statut et l'enveloppe d'erreur canonique, et vous permet d'émettre des requêtes authentifiées directement depuis la page.

## Intégration d'outils externes

Parce que les documents sont au standard OpenAPI 3.1, tout outil compatible peut les consommer une fois que vous avez récupéré le JSON en tant qu'administrateur.

| Outil              | Comment utiliser le document                                                |
| ------------------ | --------------------------------------------------------------------------- |
| Postman            | Import → File → sélectionnez `app.openapi.json` pour générer une collection |
| Insomnia           | Import / Export → Import Data → From File                                   |
| openapi-typescript | Générer des clients typés à partir de `app.openapi.json`                    |
| Redoc / Swagger UI | Pointez le visualiseur vers le fichier JSON récupéré                        |

Pour les types TypeScript côté client de la _configuration_ (pas de l'API), préférez [`@sovrium/types`](/fr/docs/json-schema#typescript-autocompletion-with-sovriumtypes) ; pour la génération de clients d'API, utilisez le document OpenAPI ci-dessus.

## Comment cela reste synchronisé

Le document OpenAPI de l'application est dérivé des mêmes schémas Zod que les routes utilisent pour la validation, et le document d'authentification est généré par Better Auth au moment de la requête. Il n'y a pas de fichier de spécification maintenu séparément qui pourrait dériver — l'ajout ou la modification du schéma de requête/réponse d'un endpoint met à jour automatiquement le document généré. Consultez la [Référence API](/fr/docs/api-reference) pour la carte des endpoints lisible par les humains.