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.

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.

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) :

# 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 :

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

Pas encore de commande export autonome. Sovrium ne livre pas actuellement de sous-commande CLI sovrium openapi destinée aux utilisateurs — 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). Le schéma JSON, en revanche, dispose d'une commande dédiée — consultez sovrium 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 ; 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 pour la carte des endpoints lisible par les humains.

← PreviousRéférence LLM Next →Licence