API Reference — Swagger UI
Chaque microservice Nex expose sa propre Swagger UI générée à partir des décorateurs @nestjs/swagger du code. C'est la source de vérité technique des contrats API : si une page de doc et la Swagger UI divergent, la Swagger UI a raison.
Endpoints Swagger par service
| Service | Port interne | Swagger UI (staging) |
|---|---|---|
| Auth | 3001 | https://dev.paywithnex.com/api/auth/docs |
| Ledger Wallets | 3002 | https://dev.paywithnex.com/api/ledger-wallets/docs |
| Customer Profiles & KYC | 3003 | https://dev.paywithnex.com/api/customer-profiles-kyc/docs |
| Orchestrator | 3004 | https://dev.paywithnex.com/api/orchestrator/docs |
| Notifications | 3005 | https://dev.paywithnex.com/api/notifications/docs |
| Configuration | 3006 | https://dev.paywithnex.com/api/configuration/docs |
| File Service | 3007 | https://dev.paywithnex.com/api/file-service/docs |
| Providers Gateway | 3008 | https://dev.paywithnex.com/api/providers-gateway/docs |
| Risk Engine | 3009 | https://dev.paywithnex.com/api/risk-engine/docs |
| Service Catalog | 3010 | https://dev.paywithnex.com/api/service-catalog/docs |
| Logs & Reporting | 3011 | ❌ Swagger non configuré (service stub v0.0.1) |
Accès staging : ces endpoints sont actuellement publics. Plan en cours : protéger derrière le même mécanisme que la doc (Cloudflare Access) — cf. /operations/cicd-deploy-docs.
En local
Quand chaque service tourne en local via make start (cf. /dev/dev-local), la Swagger UI est disponible directement sur le port du service :
| Service | URL locale |
|---|---|
| Auth | http://localhost:3001/docs |
| Ledger Wallets | http://localhost:3002/docs |
| Customer Profiles & KYC | http://localhost:3003/docs |
| Orchestrator | http://localhost:3004/docs |
| Notifications | http://localhost:3005/docs |
| Configuration | http://localhost:3006/docs |
| File Service | http://localhost:3007/docs |
| Providers Gateway | http://localhost:3008/docs |
| Risk Engine | http://localhost:3009/docs |
| Service Catalog | http://localhost:3010/docs |
Authentification
Tous les services attendent un Bearer token dans le header Authorization (cf. ADR-0002) sauf exceptions documentées :
- Endpoints publics auth (
/auth/login/*,/auth/register/*) — pas de token. - Endpoints internes inter-services (scope JWT
internal-service-jwt) — token spécifique signé par auth. - Endpoint reset-pin public (
file-service/files/public-upload/reset-pin) — token signé à usage unique.
Pour tester depuis Swagger UI : bouton Authorize en haut à droite → coller le token sans préfixe Bearer.
Devises
Tous les montants sont en bigint sérialisés en string JSON pour préserver la précision. Toujours désérialiser via BigInt(value) côté client, jamais parseInt/parseFloat.
Unités natives : XAF (BEAC) et XOF (BCEAO). Cf. /overview/glossary.
Versioning
Préfixe /v1/ sur la majorité des routes publiques (orchestrator). Les services back-facing n'utilisent généralement pas de préfixe de version (ils sont consommés en interne par l'orchestrator). Politique de versioning à formaliser dans un futur ADR.
Roadmap intégration native dans cette doc
L'objectif est d'embarquer les spec OpenAPI directement dans VitePress via un plugin (vitepress-openapi ou @scalar/vitepress-plugin) :
- Chaque service expose un endpoint
GET /api/openapi.json(déjà disponible avec@nestjs/swagger). - Le pipeline CI fetch les specs et les place dans
apps/docs/public/api/<service>.jsonavant build. - Une page par service rend la spec dans VitePress (recherche, try-it-out, exemples interactifs).
Ce travail est planifié pour un lot futur de la refonte documentaire.