itdoc – Erstellen Sie präzise Node.js-API-Dokumentation ohne Swagger

 (github.com/do-pa)
8 Punkte von penekhun 2025-06-04 | 9 Kommentare | Auf WhatsApp teilen

Einführung

Schreiben Sie API-Dokumentation immer noch manuell?
Wir haben ein Open-Source-Projekt entwickelt, das Dokumentation automatisch erstellt, wenn die Tests gut geschrieben sind.

Empfohlen für

  • Backend-Entwickler für Node.js / TypeScript
  • Alle, die API-Dokumentation schon einmal als lästig und repetitiv empfunden haben
  • Alle, die erlebt haben, dass sich tatsächliche API und Dokumentationsinhalt unterscheiden und dadurch die Zusammenarbeit ins Stocken geriet

Projektlinks

Verwandte Beiträge

9 Kommentare

 
kansm 2025-06-11

Das ist nur anhand der Dokumentation etwas schwer zu verstehen … Heißt das, dass es Swagger ersetzen kann?
Ist es besser als Swagger, kann man es also so sehen?? Haha
 
penekhun 2025-06-11

Es scheint, als müsste die README noch etwas ergänzt werden. Vielen Dank für Ihren Kommentar!

https://itdoc.kr/blog/itdoc

Ich glaube, wenn Sie diesen Artikel einmal lesen, werden sich Ihre Fragen klären, haha
 
jhc9639 2025-06-06

Ganz ordentlich, haha
 
penekhun 2025-06-07

Vielen Dank 🙇‍♂️
 
baeba 2025-06-05

Wie Sie sicher wissen ...
so etwas gibt es auch.
https://github.com/swagger-api/swagger-codegen

Wenn es das OpenAPI-Dokumentformat ist ...
wird daraus Node.js-Code erzeugt.
Als ich es ausprobiert habe, fand ich es durchaus brauchbar ...

Es generiert sowohl Server-Code als auch Client-Code ...
Wenn man bereits Erfahrung mit der Implementierung von Rest-APIs hat,
könnte es auf jeden Fall sehr hilfreich sein.

Wenn man genauer sucht ...
wird dieser Code durch Forks noch stärker weiterentwickelt.
 
penekhun 2025-06-07

Vielen Dank für den guten Kommentar!
Ich denke, dass das von Ihnen erwähnte Tool ebenfalls hervorragend ist.

Um bei dieser Gelegenheit den Unterschied zu itdoc kurz zu erläutern:Der wesentliche Unterschied ist der Ansatz Design-First vs. Code-First (itdoc).

Einige Teams bevorzugen einen Design-First-Ansatz, bei dem zuerst die OpenAPI-Spezifikation entworfen und danach mit der API-Entwicklung begonnen wird,während für andere Teams ein Code-First-Ablauf natürlicher sein kann, bei dem zunächst die tatsächliche Implementierung entsteht und die Dokumentation später daraus extrahiert wird.

itdoc ist für den letzteren Fall besser geeignet,denn ein Merkmal ist, dass die Dokumentation testbasiert anhand des tatsächlichen Verhaltens erzeugt wird. Je nach Entwicklungsweise und Präferenzen Ihres Teams können Sie das passende Tool auswählen!
 
k201gun 2025-06-05

Das Logo ist wirklich süß.
 
penekhun 2025-06-05

Vielen Dank 😆
 
penekhun 2025-06-04

Wie unten gezeigt, können Sie die Dokumentation mit menschenlesbarem Code erzeugen.

describeAPI(  
    HttpMethod.GET,  
    "/users/:userId",  
    {  
        summary: "API zum Abrufen von Benutzern",  
        tag: "User",  
        description: "Dies ist eine API zum Abrufen detaillierter Informationen zu einem bestimmten Benutzer.",  
    },  
    targetApp,  
    (apiDoc) => {  
        itDoc("Wenn eine gültige Benutzer-ID angegeben wird, werden die Detailinformationen des Benutzers zurückgegeben.", async () => {  
            await apiDoc  
                .test()  
                .req()  
                .pathParam({  
                    userId: field("Gültige Benutzer-ID", "penek"),  
                })  
                .res()  
                .status(HttpStatus.OK)  
                .body({  
                    userId: field("Benutzer-ID", "penek"),  
                    username: field("Benutzername", "hun"),  
                    email: field("E-Mail des Benutzers", "penekhun@gmail.com"),  
                    friends: field("Freunde des Benutzers", ["zagabi", "json"]),  
                })  
        })  
  ....