itdoc - Créez une documentation d’API Node.js précise sans Swagger

 (github.com/do-pa)
8 points par penekhun 2025-06-04 | 9 commentaires | Partager sur WhatsApp

Introduction

Vous rédigez encore votre documentation d’API à la main ?
Nous avons créé un projet open source qui génère automatiquement la documentation à partir de tests bien conçus.

Recommandé pour

  • Les développeurs backend Node.js / TypeScript
  • Ceux qui trouvent la rédaction de documentation d’API fastidieuse et répétitive
  • Ceux qui ont déjà connu des problèmes de collaboration parce que l’API réelle et la documentation ne correspondaient pas

Liens du projet

À lire aussi

9 commentaires

 
kansm 2025-06-11

C’est difficile à bien comprendre juste avec la documentation…

Ça veut dire que ça peut remplacer Swagger ?
On peut considérer que c’est meilleur que Swagger ?? haha
 
penekhun 2025-06-11

Il semble qu’il faille étoffer un peu plus le README. Merci pour votre commentaire !

https://itdoc.kr/blog/itdoc

Je pense qu’en lisant cet article, vos interrogations seront levées haha
 
jhc9639 2025-06-06

C'est pas mal haha
 
penekhun 2025-06-07

Merci 🙇‍♂️
 
baeba 2025-06-05

Comme vous le savez...
il y a aussi ceci.
https://github.com/swagger-api/swagger-codegen

Si c’est au format de documentation openapi...
il génère du code Node.js.
Après l’avoir essayé... j’ai trouvé ça plutôt utilisable.

Il génère à la fois le code serveur et le code client...
Pour commencer, si vous avez déjà de l’expérience en développement lié aux API REST,
je pense que cela peut beaucoup aider.

En cherchant bien... ce code a aussi été forké et davantage mis à jour.
 
penekhun 2025-06-07

Merci pour votre excellent commentaire !
Je pense également que l’outil que vous avez mentionné est excellent.

Pour expliquer brièvement la différence avec itdoc à cette occasion, la différence essentielle réside dans l’approche Design-First vs Code-First (itdoc).

Certaines équipes préfèrent une approche Design-First, qui consiste à concevoir d’abord la spécification OpenAPI puis à commencer le développement de l’API, tandis que pour d’autres équipes, un flux Code-First, où l’implémentation réelle du code est faite en premier puis la documentation est extraite ensuite, peut être plus naturel.

itdoc est un outil davantage adapté au second cas, avec pour caractéristique de générer la documentation à partir du comportement réel sur la base des tests. J’espère que vous pourrez choisir l’outil le plus adapté en fonction de la méthode de développement et des préférences de votre équipe !
 
k201gun 2025-06-05

Le logo est vraiment très mignon.
 
penekhun 2025-06-05

Merci 😆
 
penekhun 2025-06-04

Vous pouvez générer une documentation à partir d’un code lisible par un humain, comme ci-dessous.

describeAPI(  
    HttpMethod.GET,  
    "/users/:userId",  
    {  
        summary: "API de consultation d’utilisateur",  
        tag: "User",  
        description: "Cette API permet de consulter les informations détaillées d’un utilisateur spécifique.",  
    },  
    targetApp,  
    (apiDoc) => {  
        itDoc("Si un ID utilisateur valide est fourni, les informations détaillées de l’utilisateur sont renvoyées.", async () => {  
            await apiDoc  
                .test()  
                .req()  
                .pathParam({  
                    userId: field("ID utilisateur valide", "penek"),  
                })  
                .res()  
                .status(HttpStatus.OK)  
                .body({  
                    userId: field("ID utilisateur", "penek"),  
                    username: field("Nom d’utilisateur", "hun"),  
                    email: field("E-mail de l’utilisateur", "penekhun@gmail.com"),  
                    friends: field("Amis de l’utilisateur", ["zagabi", "json"]),  
                })  
        })  
  ....