Documenter une API Express avec Swagger (OpenAPI)

openapi: 3.1.1
info:
  title: API AppliFrais
  version: 1.0.0
  description: Gestion des fiches de frais des visiteurs médicaux de GSB.
servers:
  - url: http://localhost:3000
    description: Poste de développement
security:
  - jeton: []
paths:
  /v1/auth/connexion:
    post:
      summary: Se connecter et obtenir un jeton
      tags: [Authentification]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Connexion'
      responses:
        '200':
          description: Jeton d'accès valable 15 minutes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Jeton'
        '401':
          $ref: '#/components/responses/NonAuthentifie'
        '422':
          $ref: '#/components/responses/Invalide'
        '429':
          description: Trop de tentatives
  /v1/fiches/{id}/frais-hors-forfait:
    parameters:
      - { name: id, in: path, required: true, schema: { type: integer, minimum: 1 } }
    post:
      summary: Ajouter un frais hors forfait à une fiche en cours
      tags: [Fiches]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/NouveauFraisHorsForfait' }
      responses:
        '201':
          description: Frais ajouté
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FraisHorsForfait' }
        '404':
          $ref: '#/components/responses/Introuvable'
        '409':
          $ref: '#/components/responses/Conflit'
        '422':
          $ref: '#/components/responses/Invalide'
components:
  securitySchemes:
    jeton:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    NouveauFraisHorsForfait:
      type: object
      required: [date, libelle, montant]
      additionalProperties: false
      properties:
        date: { type: string, format: date }
        libelle: { type: string, minLength: 3, maxLength: 100 }
        montant: { type: number, exclusiveMinimum: 0, maximum: 5000 }
    Probleme:
      type: object
      description: Erreur au format de la RFC 9457
      properties:
        type: { type: string, format: uri }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
        instance: { type: string }
  responses:
    Conflit:
      description: État de la fiche incompatible avec l'opération
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Probleme' }

npm install swagger-ui-express yaml

// src/app.js
import { readFile } from 'node:fs/promises';
import swaggerUi from 'swagger-ui-express';
import YAML from 'yaml';

const documentation = YAML.parse(await readFile(new URL('../docs/openapi.yaml', import.meta.url), 'utf8'));

app.use('/docs', swaggerUi.serve, swaggerUi.setup(documentation));
app.get('/openapi.json', (req, res) => res.json(documentation)); // la description brute, pour les outils

import { z } from 'zod';
import { schemaFraisHorsForfait } from './schemas/fiches.schemas.js';

const { $schema, ...nouveauFrais } = z.toJSONSchema(schemaFraisHorsForfait);
documentation.components.schemas.NouveauFraisHorsForfait = nouveauFrais;

{
  "type": "object",
  "properties": {
    "date": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|…" },
    "libelle": { "type": "string", "minLength": 3, "maxLength": 100 },
    "montant": { "type": "number", "exclusiveMinimum": 0, "maximum": 5000, "multipleOf": 0.01 }
  },
  "required": ["date", "libelle", "montant"],
  "additionalProperties": false
}

// test/documentation.test.js
import assert from 'node:assert/strict';
import { readFile } from 'node:fs/promises';
import { after, before, describe, it } from 'node:test';
import request from 'supertest';
import YAML from 'yaml';
import { app } from '../src/app.js';
import { pool } from '../src/db.js';
import { jetonDe, reinitialiserBase } from './outils.js';

const documentation = YAML.parse(await readFile(new URL('../docs/openapi.yaml', import.meta.url), 'utf8'));
const METHODES = ['get', 'post', 'put', 'patch', 'delete'];

let jeton;
before(async () => {
  await reinitialiserBase();
  jeton = await jetonDe('adurand', 'Comptable#2026');
});
after(() => pool.end());

describe('docs/openapi.yaml', () => {
  for (const [chemin, operations] of Object.entries(documentation.paths)) {
    for (const methode of METHODES.filter((m) => operations[m])) {
      it(`${methode.toUpperCase()} ${chemin} existe dans l'API`, async () => {
        const url = chemin.replaceAll(/\{[^}]+\}/g, '1'); // /v1/fiches/{id} devient /v1/fiches/1
        const reponse = await request(app)[methode](url).set('Authorization', jeton);
        assert.notEqual(reponse.body.type, 'https://api.gsb.example/problemes/route-inconnue');
      });
    }
  }
});

▶ docs/openapi.yaml
  ✔ POST /v1/auth/connexion existe dans l'API (2.7ms)
  ✔ GET /v1/fiches existe dans l'API (2.3ms)
  ✔ POST /v1/fiches existe dans l'API (1.4ms)
  ✔ GET /v1/fiches/{id} existe dans l'API (1.6ms)
  ✔ POST /v1/fiches/{id}/frais-hors-forfait existe dans l'API (1.1ms)

'409':
  description: >-
    La fiche n'est plus en cours (état CL, VA ou MP) : ses frais ne se modifient plus.
  content:
    application/problem+json:
      schema: { $ref: '#/components/schemas/Probleme' }
      examples:
        ficheCloturee:
          summary: Ajout sur une fiche clôturée
          value:
            type: https://api.gsb.example/problemes/fiche-cloturee
            title: Fiche non modifiable
            status: 409
            detail: "La fiche est à l'état CL : seuls les frais d'une fiche en cours se modifient."
            instance: /v1/fiches/12/frais-hors-forfait
            etatActuel: CL

# API AppliFrais

API REST de gestion des frais des visiteurs médicaux GSB (Node.js 24, Express 5, MySQL 8.4).

## Démarrer
1. npm ci
2. Créer la base : voir sql/schema.sql et sql/donnees.sql
3. cp .env.example .env, puis compléter les valeurs
4. npm run dev, puis ouvrir http://localhost:3000/docs

## Comptes de démonstration (jeu de données de test uniquement)
- lmartin / Visiteur#2026 (visiteur)
- adurand / Comptable#2026 (comptable)

## Scripts
- npm run dev : développement, relance automatique
- npm test : tests (base applifrais_test, fichier .env.test)
- npm start : production

## Variables d'environnement
DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME, JWT_SECRET (32 caractères au moins),
CORS_ORIGIN, PORT, LOG_LEVEL, DOSSIER_JUSTIFICATIFS