最近、業務でよくAPI仕様書を作っています。
markdownでせっせと書いていたのですが、同チームのエンジニアからドキュメント作成ツールとか使ってみると便利だよとアドバイスをいただきました。
「そんなものあるのかー」と思い、気になったので調べてみました。
API Blueprint
APIドキュメントを書くツール。markdownに慣れている人にとっては使いやすいと思いました。
実際に試してみた
ググりながら試しに使ってみます。
環境構築：https://qiita.com/takahyon/items/399e3d5781e0f6c73e06
記法：https://dev.classmethod.jp/server-side/api-document-with-api-blueprint/
表示するだけならhomebrewが導入済みなら数分で完了しました。記法については、markdownに似ているので、あまり違和感なく操作できました。
ただ、API Blueprint独特の書き方も存在するので、細かく書くには多少勉強が必要になりそうです。
下記は公式sampleの出力結果です。
感想
作成したドキュメントをhtmlファイルに出力することも可能なので、ドキュメントを気軽に共有することができます。また、API Blueprintを調べる中で"一般的なドキュメントの構成"も合わせて調べることができたので、ドキュメント作成の学びになりました。
今回のドキュメント作成は慣れているmarkdownで作成しましたが、機会があれば実際にAPI Blueprintを導入してみたいと思います。