Documentation Swagger avec Next.js

Swagger UI permet de créer une documentation interactive et professionnelle pour vos APIs Next.js. Dans ce tutoriel, nous allons intégrer Swagger dans votre application Next.js.

Installation et configuration

Installation des dépendances

npm install swagger-ui-react swagger-jsdoc
npm install --save-dev @types/swagger-ui-react @types/swagger-jsdoc

Configuration de base

// lib/swagger.js
import swaggerJSDoc from 'swagger-jsdoc'

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Mon API Next.js',
      version: '1.0.0',
      description: 'Documentation de l\'API créée avec Next.js',
      contact: {
        name: 'Support API',
        email: 'support@monapi.com',
        url: 'https://monapi.com/support'
      }
    },
    servers: [
      {
        url: 'http://localhost:3000/api',
        description: 'Serveur de développement'
      }
    ],
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT'
        }
      }
    }
  },
  apis: ['./pages/api/**/*.js'], // Chemins vers vos fichiers API
}

export const swaggerSpec = swaggerJSDoc(options)

Page de documentation

// pages/api-docs.js
import dynamic from 'next/dynamic'
import { swaggerSpec } from '../lib/swagger'

const SwaggerUI = dynamic(() => import('swagger-ui-react'), { ssr: false })

export default function ApiDocs({ spec }) {
  return (
    <div style={{ height: '100vh' }}>
      <SwaggerUI spec={spec} />
    </div>
  )
}

export const getStaticProps = async () => {
  return {
    props: {
      spec: swaggerSpec
    }
  }
}

Documentation des endpoints

Annotations de base

/**
 * @swagger
 * /api/users:
 *   get:
 *     summary: Récupère la liste des utilisateurs
 *     description: Retourne tous les utilisateurs avec pagination
 *     tags: [Users]
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           default: 1
 *         description: Numéro de page
 *     responses:
 *       200:
 *         description: Liste des utilisateurs récupérée avec succès
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 users:
 *                   type: array
 *                   items:
 *                     $ref: '#/components/schemas/User'
 */

// pages/api/users/index.js
export default function handler(req, res) {
  // Votre logique d'API ici
}

Définition des schémas

/**
 * @swagger
 * components:
 *   schemas:
 *     User:
 *       type: object
 *       required:
 *         - id
 *         - name
 *         - email
 *       properties:
 *         id:
 *           type: integer
 *           description: ID unique de l'utilisateur
 *           example: 1
 *         name:
 *           type: string
 *           description: Nom complet de l'utilisateur
 *           example: "Jean Dupont"
 *         email:
 *           type: string
 *           format: email
 *           description: Adresse email de l'utilisateur
 *           example: "jean.dupont@example.com"
 */

Authentification dans Swagger

Documentation de l’authentification

/**
 * @swagger
 * /api/auth/login:
 *   post:
 *     summary: Connexion utilisateur
 *     description: Authentifie un utilisateur et retourne un token JWT
 *     tags: [Authentication]
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - email
 *               - password
 *             properties:
 *               email:
 *                 type: string
 *                 format: email
 *                 example: "user@example.com"
 *               password:
 *                 type: string
 *                 example: "motdepasse123"
 *     responses:
 *       200:
 *         description: Connexion réussie
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 token:
 *                   type: string
 *                   description: Token JWT pour l'authentification
 *                 user:
 *                   $ref: '#/components/schemas/User'
 */

Upload de fichiers

/**
 * @swagger
 * /api/upload:
 *   post:
 *     summary: Upload d'un fichier
 *     description: Télécharge un fichier sur le serveur
 *     tags: [Files]
 *     security:
 *       - bearerAuth: []
 *     requestBody:
 *       required: true
 *       content:
 *         multipart/form-data:
 *           schema:
 *             type: object
 *             properties:
 *               file:
 *                 type: string
 *                 format: binary
 *                 description: Fichier à télécharger
 *     responses:
 *       200:
 *         description: Fichier uploadé avec succès
 */

Personnalisation de Swagger UI

// pages/api-docs.js (version améliorée)
import dynamic from 'next/dynamic'
import Head from 'next/head'
import { swaggerSpec } from '../lib/swagger'

const SwaggerUI = dynamic(() => import('swagger-ui-react'), { ssr: false })

export default function ApiDocs({ spec }) {
  return (
    <>
      <Head>
        <title>Documentation API - Mon App Next.js</title>
        <meta name="description" content="Documentation interactive de l'API" />
      </Head>
      
      <div style={{ height: '100vh' }}>
        <SwaggerUI 
          spec={spec}
          docExpansion="list"
          defaultModelsExpandDepth={2}
          displayRequestDuration={true}
          tryItOutEnabled={true}
          filter={true}
        />
      </div>
    </>
  )
}

Génération automatique

Script de génération

// scripts/generate-swagger.js
const fs = require('fs')
const path = require('path')
const { swaggerSpec } = require('../lib/swagger')

// Générer le fichier JSON
const outputPath = path.join(process.cwd(), 'public', 'swagger.json')
fs.writeFileSync(outputPath, JSON.stringify(swaggerSpec, null, 2))

console.log('Swagger JSON généré:', outputPath)

Script package.json

{
  "scripts": {
    "swagger:generate": "node scripts/generate-swagger.js",
    "dev": "npm run swagger:generate && next dev",
    "build": "npm run swagger:generate && next build"
  }
}

Bonnes pratiques

1. Organisation des annotations

Séparez les annotations dans des fichiers dédiés pour une meilleure maintenabilité.

2. Versioning de l’API

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Mon API Next.js',
      version: '2.1.0', // Versioning sémantique
      description: 'API version 2.1 avec nouvelles fonctionnalités'
    }
  }
}

3. Documentation des exemples

Incluez des exemples concrets pour faciliter la compréhension.

Tests et validation

// __tests__/swagger.test.js
import { swaggerSpec } from '../lib/swagger'
import SwaggerParser from '@apidevtools/swagger-parser'

describe('Swagger Documentation', () => {
  test('should have valid OpenAPI specification', async () => {
    await expect(SwaggerParser.validate(swaggerSpec)).resolves.toBeDefined()
  })
})

Swagger UI transforme vos APIs Next.js en documentation interactive et professionnelle. Vos utilisateurs peuvent maintenant tester et comprendre facilement votre API !

Ressources utiles

API Routes Projet complet