API Swagger - Documentation OpenAPI

Vue d'ensemble

Tranoo expose sa documentation API via OpenAPI 3.0 et Swagger UI.

Élément	Détail
Spec	OpenAPI 3.0.0
UI	swagger-ui-express
Approche	Spec écrite manuellement en JavaScript (objets JS)
Couverture	Script automatique qui compare routes Express ↔ doc OpenAPI

Accès à la documentation

Environnement de développement

• Swagger UI : http://localhost:5000/api-docs
• Spec JSON : http://localhost:5000/api-docs.json

Production

• Swagger UI : https://api.tranoo.store/api-docs
• Spec JSON : https://api.tranoo.store/api-docs.json

Architecture des fichiers

src/docs/openapi/
├── index.js                # Assemble info, tags, components, paths
├── components.js           # Schémas partagés + securitySchemes
├── tags.js                 # Catégories affichées dans Swagger UI
├── helpers.js              # Utilitaires (op, authed, jsonBody…)
├── README.md               # Aide-mémoire rapide
└── paths/                  # Un fichier JS par domaine fonctionnel
    ├── 01-health-auth.js
    ├── 02-users-settings.js
    ├── 03-articles-public.js
    ├── 04-publicites-chauffeur-chat.js
    ├── 05-achat-notifications.js
    ├── 06-payments-wallet.js
    ├── 07-verification-orders-invoices.js
    ├── 08-deliveries-zones-livreurs.js
    ├── 09-tricycles-referrals-agents.js
    ├── 10-views-admin-geo-whatsapp.js
    └── 11-transitaires-transit-stats.js

Structure de la spécification

index.js - Assemblage principal

• Informations générales (title, version, description)
• Tags (catégories)
• Components (schémas partagés)
• Paths (endpoints)
• SecuritySchemes (authentification)

components.js - Schémas partagés

Schémas réutilisables via $ref :

Schéma	Description
ApiError	Format erreur standard (success, code, message)
ApiSuccess	Réponse succès générique
RegisterRequest	Body inscription
WebSessionStart	Démarrage session web
PasswordResetRequest	Demande reset OTP
VerifyResetCode	Vérification code OTP
ResetPassword	Nouveau mot de passe
UserSettings	Langue, devise, notifications
ArticleInput	Création/modification article
OrderInput	Création commande
DeliveryInput	Création livraison
ChatMessage	Message chat
GeoPoint	Coordonnées lat/lng
PaginationQuery	page, limit

tags.js - Catégories Swagger UI

Tag	Domaine
Santé	GET /
Authentification	register, sessions web
Utilisateurs	CRUD users, favoris, FCM
Paiements	FeexPay, webhooks
Livraisons	Cycle livraison
Admin — Tarifs	Tarifs pub, abonnement, vérification

helpers.js - Utilitaires

Helper	Usage
op(tag, summary, opts)	Opération générique
authed(tag, summary, opts)	Opération avec security: [bearerAuth]
jsonBody(schemaRef, opts)	Body application/json
multipartBody(description)	Body multipart/form-data
pathParam(name, description, type)	Paramètre {id} dans l'URL
queryParam(name, description, opts)	Query string ?page=1
OK, CREATED, NO_CONTENT	Réponses succès courantes

Authentification

Schéma de sécurité

securitySchemes: {
  bearerAuth: {
    type: 'http',
    scheme: 'bearer',
    bearerFormat: 'JWT',
    description: 'Firebase ID token (header Authorization: Bearer …)',
  },
}

Headers spécifiques web

Header	Usage
Authorization: Bearer <token>	Auth Firebase (mobile + web)
X-Client-Platform: web	Session dashboard web
X-Web-Session-Id: <uuid>	Session unique dashboard

Utilisation dans Swagger UI

1. Cliquer sur Authorize (cadenas)
2. Coller le token Firebase : Bearer eyJhbG... ou juste eyJhbG...
3. Les routes marquées authed() exigent ce token

Commandes npm

Compter les endpoints documentés

npm run swagger:count
# Affiche le nombre de paths documentés

Vérifier la couverture

npm run swagger:verify
# Compare les routes Express avec la doc OpenAPI
# Affiche les endpoints manquants ou en trop

Workflow : Ajouter un nouvel endpoint

Cas A - Endpoint dans un domaine existant

1. Créer la route dans src/routes/<domaine>.js
2. Vérifier le montage dans src/app.js
3. Documenter dans le fichier paths/ correspondant :

Route montée	Fichier paths
/api/auth, /api/protected, /api/push-otp	01-health-auth.js
/api/users, /api/settings	02-users-settings.js
/api/articles, /api/public, /api/upload	03-articles-public.js
/api/publicites, /api/chauffeurs, /api/chat	04-publicites-chauffeur-chat.js
/api/achat, /api/notifications	05-achat-notifications.js
/api/payments, /api/wallet	06-payments-wallet.js
/api/verification, /api/orders, /api/invoices	07-verification-orders-invoices.js
/api/deliveries, /api/delivery-zones, /api/livreurs	08-deliveries-zones-livreurs.js
/api/tricycles, /api/referrals, /api/agents	09-tricycles-referrals-agents.js
/api/views, /api/admin/*, /api/geo, /api/whatsapp	10-views-admin-geo-whatsapp.js
/api/transitaires, /api/transit	11-transitaires-transit-stats.js

4. Vérifier :

npm run swagger:verify
npm run swagger:count

5. Tester visuellement : npm run dev → http://localhost:5000/api-docs

Cas B - Nouveau préfixe /api/mon-domaine

1. Créer src/routes/monDomaine.js
2. Monter dans src/app.js
3. Créer ou étendre un fichier dans paths/ (ex. 12-mon-domaine.js)
4. Si nouveau domaine métier : ajouter un tag dans tags.js
5. npm run swagger:verify

Exemples d'opérations

Route publique

const { op, jsonBody } = require('../helpers');

module.exports = {
  '/api/auth/register': {
    post: op('Authentification', 'Inscription utilisateur', {
      description: 'Crée un compte Firebase + document MongoDB.',
      security: [],
      requestBody: jsonBody('#/components/schemas/RegisterRequest'),
      responses: { 201: { description: 'Ressource créée' } },
    }),
  },
};

Route protégée

const { authed, pathParam, OK } = require('../helpers');

module.exports = {
  '/api/users/{id}': {
    get: authed('Utilisateurs', 'Détail utilisateur par ID', {
      parameters: [pathParam('id', 'ID MongoDB utilisateur')],
      responses: { 200: OK },
    }),
  },
};

Webhook (sans Bearer)

const { op, jsonBody, OK } = require('../helpers');

module.exports = {
  '/api/payments/feexpay/webhook': {
    post: op('Paiements', 'Webhook FeexPay', {
      description: 'Callback serveur FeexPay (sans auth Bearer).',
      security: [],
      requestBody: jsonBody(null),
      responses: { 200: OK },
    }),
  },
};

État actuel

• 245 paths documentés (npm run swagger:count)
• Couverture vérifiée par npm run swagger:verify (quelques endpoints admin encore non documentés)

Endpoints non documentés (à compléter)

• GET /api/admin/documents/{id}/download
• GET|POST|PUT /api/admin/seller-gain-pricing
• GET /api/notifications/admin-messages/history
• GET /api/verification/admin/requests
• GET /api/verification/admin/stats
• PATCH /api/verification/admin/requests/{articleId}/statut

Guide complet : tranoo-api/docs/SWAGGER.md

Importer la spec dans d'autres outils

Postman

Import → Link → https://api.tranoo.store/api-docs.json

curl

curl -s http://localhost:5000/api-docs.json | head -c 200

Bonnes pratiques

1. Toujours lancer npm run swagger:verify avant de merger une PR
2. Un endpoint = une entrée dans le bon fichier paths/
3. Utiliser les helpers (authed, jsonBody, pathParam)
4. Réutiliser les schémas components.js pour les bodies récurrents
5. Choisir le bon tag (voir tags.js)
6. Marquer les routes deprecated avec deprecated: true
7. Documenter les particularités dans description

Voir aussi

• Architecture Backend — documentation backend complète
• Base de données — schémas MongoDB
• Transit international — domaine transitaires
• Agents commerciaux — domaine agents et démos