itdoc - Swaggerなしで正確なNode.js APIドキュメントを作ってみましょう

紹介

APIドキュメントを、まだ手作業で書いていますか？
テストさえきちんと書けば、ドキュメントが自動で作られるオープンソースを作りました。

こんな方におすすめです

• Node.js / TypeScript バックエンド開発者
• APIドキュメント作成が面倒で反復的だと感じたことがある
• 実際のAPIとドキュメント内容が異なり、コラボレーションがうまくいかなかった経験がある

プロジェクトリンク

• Github : https://github.com/do-pa/itdoc
• 公式ドキュメント : https://itdoc.kr

[kansm]

これは文書だけ見てもいまいちよく分からないのですが……Swaggerの代わりにできるということですよね?
Swaggerより優れていると見ればいいのでしょうか?? haha

[penekhun]

README をもう少し補強する必要がありそうですね。コメントありがとうございます！

https://itdoc.kr/blog/itdoc

この記事を一度読んでいただければ、疑問が解消されると思います（笑）

[jhc9639]

なかなかいいですね（笑）

[penekhun]

ありがとうございます 🙇‍♂️

[baeba]

ご存じのとおりですが..
こういうものもあります。
https://github.com/swagger-api/swagger-codegen

openapiのドキュメントフォーマットであれば..
node.jsのコードを生成してくれます。
使ってみると.. なかなか実用的でした。

サーバーコードもクライアントコードも生成してくれるので..
ひとまず既存のRest API関連のコーディング経験があれば
かなり役に立つのではないかと思います。

よく探してみると.. 該当コードをフォークしてさらに多く更新しているものもあります。

[penekhun]

良いコメントをありがとうございます！
ご指摘いただいたツールも素晴らしいと思います。

この機会にitdocとの違いを簡単にご説明すると、核心的な違いはまさに Design-First と Code-First（itdoc）というアプローチです。

OpenAPI仕様を先に設計してからAPI開発を始めるDesign-First方式を好むチームもあれば、実際のコード実装を先に行い、あとからドキュメントを抽出するCode-Firstの流れのほうが自然なチームもあります。

itdocは後者の場合により適したツールで、テストベースで実際の動作にもとづいてドキュメントを生成する点が特徴です。チームの開発方式や好みに応じて、適切なツールを選んでいただければと思います！

[k201gun]

ロゴが本当にかわいいですね

[penekhun]

ありがとうございます 😆

[penekhun]

以下のように、人が読めるコードでドキュメントを生成できます。

describeAPI(  
    HttpMethod.GET,  
    "/users/:userId",  
    {  
        summary: "ユーザー取得API",  
        tag: "User",  
        description: "特定のユーザーの詳細情報を取得するAPIです。",  
    },  
    targetApp,  
    (apiDoc) => {  
        itDoc("有効なユーザーIDが与えられると、ユーザーの詳細情報が返される。", async () => {  
            await apiDoc  
                .test()  
                .req()  
                .pathParam({  
                    userId: field("有効なユーザーID", "penek"),  
                })  
                .res()  
                .status(HttpStatus.OK)  
                .body({  
                    userId: field("ユーザーID", "penek"),  
                    username: field("ユーザー名", "hun"),  
                    email: field("ユーザーのメールアドレス", "[e-mail]"),  
                    friends: field("ユーザーの友人", ["zagabi", "json"]),  
                })  
        })  
  ....