分かりやすいドキュメントを。APIドキュメントジェネレータまとめ
最近の記事
APIはシステム用の機能になります。分かりやすいビジュアル化された画面がある訳ではありませんので、使い方のドキュメントが必須です。
今回はAPIドキュメントを生成するためのライブラリを紹介します。
Swagger | The World's Most Popular Framework for APIs.
SwaggerはRESTfulなAPIドキュメント生成に対応したツールとなっています。ドキュメントはYAMLを使って記述します。また、Web上でテスト実行できる仕組みが便利です。
RAML - RESTful API modeling language
RAMLとはRESTful API Modeling Languageの略で、YAMLフォーマットを使ってRESTfulなAPIドキュメントを作成します。専用のエディタもあり、プレビューで確認しながらドキュメントが書けます。
apiDoc - Inline Documentation for RESTful web APIs
apiDocは各プログラミング言語にコメントを使ってインラインで記述するAPIドキュメントになります。JavaDocやPHPDocなどに近いものです。ドキュメントとソースコードが近くにあるので内容が乖離しづらいのが利点でしょう。
API Blueprint - API Documentation with powerful tooling
API BlueprintはMarkdown記法に沿って書くAPIドキュメントです。単純にドキュメントだけでなく、API BlueprintをベースにしたAPIモックサーバ、テストツールなどが存在します。
mashery/iodocs
JSONフォーマットで定義するAPIドキュメントになります。ドキュメント上から実際にAPIのコールができるのが特徴になります。
rjha/restdoc
PHP製のスクリプトでYAMLフォーマットの定義からドキュメントを生成します。スクリプト言語なのでYAMLを更新するだけでいつでも最新のドキュメントが読めるのは良さそうです。
MireDot | REST API Documentation Generator for Java
Javaで作られたシステム用のAPIドキュメントジェネレータです。JavaDocのように簡単に、とあるのでJavaDocを書かれた経験がある方であればすぐに使いこなせるでしょう。
ehearty/Swadl
RESTful APIにおけるWSDLとも言えるWADLをベースにドキュメントを生成するソフトウェアです。
Apiary - Home
APIの仕様を定義するとドキュメントの生成はもちろん、APIモックの生成、コードサンプル、テスト自動化など複合的にサービスを提供しています。
tombenke/rest-tool
nodeで作られたライブラリで、JSONフォーマットで定義した内容を読み取ってドキュメントを生成します。
malachheb/calamum
JSON/YAMLで書かれたファイルからドキュメントを生成します。
APIドキュメントを適切に整備していくためにはツールの使いやすさはもちろんのこと、ベースになる記法やそのルールの分かりやすさも重要になってくるでしょう。
ぜひこれらのツールを参考に、他の開発者にとって分かりやすいドキュメントを書いてください。