RESTful APIのドキュメンティングツール比較
概要
いままでチームで、ConfluenceにAPI仕様書を書いてました.
今回新たに別ドメインのAPIを用意するにあたり、ナウくてイケてるAPIドキュメンティングトツールを採用したいと思い調査しました.
個人メモなので結構緩めです.
要求
ざっくりこうあってほしいということ.
- メンテナンスが簡単
- 記述フォーマットが簡単
- 一般的なフォーマットだとエディタの恩恵を受けやすい
- 仕様書を簡単に公開できる
- ローカル環境でいちいちなにかすることなく、簡単にだれでもAPI仕様を閲覧できるようにしたい
- MockAPIの立ち上げができること
- 簡単に試せるようにしたい
結論
結論からいうと、Swaggerを採用することにしました.
- OpenAPI InitiativeがRESTful API の標準化をしており、ドキュメンティングツールとしてSwaggerを採用
- 今後の標準になる見込み.
- Swagger形式が、AWSやGCPですでに使われている.
- APIモックサーバの立ち上げや検証機能など、一通りのツールが揃っている.
比較
比較する候補
JSON Schema
JSON値の形式を定義、検証するための仕様です.
JSON文書の検証、APIドキュメント生成ができます.
JSONの記載は手動なので、多少つらみはあるかもしれません.
API Blueprint
APIドキュメンティングツール.
yamlの拡張形式で、APIの形式を表現できます.
Swaggerよりも簡単に導入できそうですが、記述方式に若干の癖がありコストがかかりそうという印象.
Swagger(OpenAPI)
上記同様APIドキュメンティングツール.
OpenAPI InitiativeがRESTful API の標準化をしており、ドキュメンティングツールとしてSwaggerを採用されたようです.
したがって今後API仕様の標準となりそうです.
各要素の比較
| 観点＼項目 | JSON Schema | API Blueprint | Swagger(OpenAPI) |
|---|---|---|---|
| フォーマット | JSON | MSON(独自) | JSON, YAML |
| サーバスタブコード生成 | ☓ | ◯ | ◯ |
| クライアントライブラリ生成 | ☓ | ◯ | ◯ |
| モックサーバ立ち上げ | ☓ | ◯ | ◯ |
| HTML生成、公開 | ☓ | △ | ◯ |
| パブリッククラウド採用(AWS, GCP) | ☓ | ☓ | ◯ |
以下、比較についての補足です.
フォーマット
エディタの対応状況を考えると個人的にはYAMLがやりやすいです.
HTML生成、公開
- API Blueprintは Apiary を使ってホスティングできる(有料)
- Swaggerは redoc をつかって静的なHTMLページを簡単に作ることができる.
- Github Page 、AWS S3から無料で簡単にドキュメントを公開できる.
おわりに
次は ReDoc についてまとめようと思います。
