Documenter une API : OpenAPI & Swagger

Introduction

Tu développes une API REST pour ton SaaS ? Tu veux qu’elle soit comprise rapidement, testable et adoptée par tes utilisateurs ou partenaires ?
Alors tu dois documenter ton API proprement, de façon à la fois lisible par des humains… et par des machines.
Dans cet article, on te montre comment générer une documentation professionnelle avec OpenAPI et Swagger, sans y passer des heures.

Pourquoi documenter son API est indispensable

Une API sans documentation, c’est comme une bibliothèque sans plan : inutilisable ou frustrante.
Pour un SaaS, une documentation claire :

• réduit les tickets support

• accélère l’onboarding dev

• renforce la crédibilité de ton produit

💡 Et côté SEO ? Une API bien documentée peut attirer du trafic qualifié via des requêtes techniques (devs, intégrateurs, CTO…).

OpenAPI vs Swagger : comprendre les bases

Qu’est-ce que OpenAPI ?

OpenAPI est un standard ouvert (anciennement Swagger Spec) pour décrire les API REST en JSON ou YAML.
Il permet de générer des docs lisibles, tester les endpoints, et même générer du code client automatiquement.

Et Swagger alors ?

Swagger est une suite d’outils autour du standard OpenAPI :

• Swagger Editor : écrire et valider ta spec OpenAPI

• Swagger UI : générer une documentation web interactive

• Swagger Codegen : générer des SDK ou stubs à partir de ta spec

Avantages de la génération de documentation automatique

Étapes pour créer une documentation API propre avec OpenAPI

1. Décrire ton API au format OpenAPI (YAML ou JSON)

Tu peux l’écrire manuellement ou la générer depuis ton code si tu utilises :

• NestJS → @nestjs/swagger

• Express + Typescript → tsoa ou swagger-jsdoc

• FastAPI (Python) → natif via doc automatique

• Spring Boot → avec springdoc-openapi

Exemple de spec minimaliste en YAML :

openapi: 3.0.0
info:
  title: Product Fetcher API
  version: 1.0.0
paths:
  /products:
    get:
      summary: Liste les produits disponibles
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        price:
          type: number

2. Afficher la documentation avec Swagger UI

Tu peux héberger ta doc interactive à /docs ou /api-docs de ton SaaS.
Exemple en Express (Node.js) :

import swaggerUi from 'swagger-ui-express'
import swaggerDocument from './swagger.json'

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument))

Résultat : une interface web interactive comme https://petstore.swagger.io/

3. Intégrer dans ta CI/CD (bonus)

À chaque build, tu peux :

• Générer automatiquement la doc

• Valider le schéma (ex : via swagger-cli validate)

• Publier sur un CDN ou dans ton interface client dev

Meilleures pratiques pour une doc API lisible et utile

• Utilise des verbes HTTP clairs (GET, POST, PUT, DELETE)

• Ajoute un résumé à chaque endpoint

• Précise les codes de réponse (200, 400, 401, 500...)

• Documente les erreurs (structure, exemple, message)

• Montre des exemples concrets (avec curl ou JSON)

• Ajoute des tags (ex : auth, billing, user) pour organiser les routes

Outils complémentaires à Swagger/OpenAPI

Intégrer ta doc dans ton SaaS

• Lien vers la doc API dans la page compte / dev

• Ajout d’un menu "Documentation API" sur ton site public

• Authentification de test via tokens temporaires ou sandbox

🔗 Découvre d'autres pratiques pour structurer la partie dev de ton SaaS sur SaaS Path

Conclusion

Une documentation API automatisée et bien structurée est un gain énorme pour ton SaaS :
moins de support, plus de crédibilité, plus de conversions devs.
Avec OpenAPI et Swagger, tu peux générer cette doc en continu sans effort manuel.