Validation et génération de code à partir de la documentation

La section précédente nous montre comment documenter notre API à l'aide du standard OpenAPI Specification (OAS) dans un format JSON. En plus d'indiquer aux clients de l'API les routes offertes et les paramètres attendus, nous avons vus que le fait de suivre un standard nous permet de générer un site web interactif qui offre des fonctionalités de test similaires à Postman directement de notre documentation (outil Swagger UI)

OAS est assez précis pour aussi permettre l'automatisation de:

• La validation des paramètres d'entrée et de sortie
• La génération de code pour les routes et controlleurs dans Express
• La génération de code pour les clients de l'API dans différents langages

Validation avec express-openapi-validator

express-openapi-validator est un intergiciel (middleware) Express qui vérifie automatiquement chaque requête entrante et sortante en utilisant notre spécification OpenAPI (OAS). Tout ce qui peut s'exprimer en termes de règles de validation dans OAS va être appliqué automatiquement et les erreurs HTTP correspondantes vont être retournées en cas d'erreur.

Une erreur de validation de requête renvoie un 400 (faute du client), mais une erreur de validation de réponse renvoie une 500 (faute du développeur).

Installation

npm install express-openapi-validator

Utilisation

// Généré via Gemini - fév 2026

import express from 'express';
import path from 'path';
import { fileURLToPath } from 'url';
import * as OpenApiValidator from 'express-openapi-validator';

const app = express();
const port = 3000;

// Replicate __dirname for ES Modules
const __dirname = path.dirname(fileURLToPath(import.meta.url));

app.use(express.json());

// 1. Install the Validator Middleware pointing to the JSON file
app.use(
  OpenApiValidator.middleware({
    apiSpec: path.join(__dirname, './documentation.json'), // Path to your .json file
    validateRequests: true,
    validateResponses: true
  })
);

// 2. Your Route
app.post('/books', (req, res) => {
  // Validation has already occurred
  res.status(201).json({ 
    message: 'Book validated and created!', 
    received: req.body 
  });
});

// 3. Standard Error Handler - Intergiciel (middleware) avec 4 arguments (vs les 3 habituels)
app.use((err, req, res, next) => {
  res.status(err.status || 500).json({
    message: err.message,
    errors: err.errors,
  });
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

Génération de code serveur

À partir de notre doc OAS, nous pouvons aussi générer du code serveur pour Express, où les routes et controlleurs de base seront obtenus automatiquement. La validation des paramètres d'entrée et de sortie peut toujours être effectuée à l'aide de l'intergiciel (middleware) OpenApiValidator.

(exemple généré à l'aide de Google Gemini, fév 2026)

Génération

npx @openapitools/openapi-generator-cli generate \
  -i users_openapi_doc.json \
  -g nodejs-express-server \
  -o ./generated-server

(-g -> generator, -o -> output dir)

Fichiers générés

import * as UserModel from '../models/UserModel.js';  // Notre mise en oeuvre

export const getUserByName = async (request, response) => {
  try {
    const { username } = request.params;
    // Calling the business logic layer
    const result = await UserModel.getUserByName(username);

    response.status(200).json(result);
  } catch (error) {
    response.status(error.status || 500).send(error.message);
  }
};

import express from 'express';
import * as UserController from '../controllers/UserController.js';

const router = express.Router();

/**
 * GET /user/:username
 * Maps to the controller function
 */
router.get('/:username', UserController.getUserByName);

export default router;

import express from 'express';
import { fileURLToPath } from 'url';
import path from 'path';
import * as OpenApiValidator from 'express-openapi-validator';
import userRouter from './routes/UserRoutes.js'; 

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const specDoc = path.join(__dirname, 'api/openapi.json');

const app = express();

app.use(express.json());

// The library sets up the "rules" of your API
app.use(
  OpenApiValidator.middleware({
    apiSpec: specDoc,
    validateRequests: true,
  })
);

// Mounts the generated routes
app.use('/api', userRouter);

app.listen(3000, () => {
  console.log('Main Server running on http://localhost:3000');
  console.log('OpenAPI logic is active at /api');
});