APIを作る機会が増えてきている
- 例えばマイクロサービス間はAPIでやりとりすることが多い。
- 外部のサービスもだいたいAPIでやりとりする。
- 社内APIもいくつかあるが、いざ使おうとなるとどんなリクエストを送るべきなのか、またどんなリクエストが返ってくるのかを調べるのが面倒。
API ドキュメントを書くのは大変
- フォーマットは？ Markdown? HTML? Text?
- エンジニア間で書き方がバラバラにならない？
- そのドキュメントの内容は今も正しい？
- そもそも書くのが面倒…
ということで、いい感じのAPIドキュメントツールがほしい
API ドキュメントツールに求めること その1
- ドキュメントが書きやすい
- ドキュメントが読みやすい
- ドキュメントがGitで管理しやすい
- リクエスト情報、レスポンス情報が見やすい
- curlですぐに試せるようにサンプルがほしい
- ドキュメントとコードに乖離がないようにしたい
ここまでは一般的な要求。しかしAPIドキュメントにリクエスト/レスポンス情報の構造や型情報、ステータスコード、ヘッダー情報が書かれているともっと多くのことを望むようになる。
API ドキュメントツールに 求めること その2
- APIドキュメント内のリクエスト情報とレスポンス情報を用いてプログラムのバリデートしたい
- APIドキュメントからプログラムを自動生成したい
- プログラムからAPIドキュメントを自動生成したい
- APIドキュメントからモックサーバーをたちあげたい
有名なAPI ドキュメント ツール
- Swagger
- API Blueprint
- JSON Schema
- RAML
Swagger
- SwaggerはREST APIの記述に関する仕様とそれら周辺のツールを指す
- Open API InitiativeというREST APIの記述標準化を進める団体があり、その標準フォーマットがSwagger
- YAML/JSONで記述する。例
- もっとも大きく、そして高機能
- 比較的読みやすい
API Blueprint
- Web APIの仕様をMarkdown拡張形式で記述する
- 人が読み書きしやすいフォーマット
- もともとはApiaryというサービスで使用するフォーマットで、それが普及した
JSON Schema
- JSONの構造(schema)や各要素の型を定義するフォーマット
- JSON/YAMLで記述する
- JSON Hyper-Schemaという仕様があり、Web APIの仕様が定義できる
- (そのままでは)API仕様書としては読みにくい
RAML
- YAMLを使ってAPI仕様を記述する
- 他のツールに比べて後発
- 他のAPIドキュメントよりは読みやすい
- Swaggerに似ている
今回紹介するのはAPI Blueprintとその周辺ツール
API Blueprintの例
Markdownでもいいけど、もうちょっとかっこいいAPIドキュメントがほしい
aglio
- https://github.com/danielgtaylor/aglio
- API BlueprintをHTMLに変換してくれるツール
- 複数のAPI Blueprintファイルを一つのHTMLにできる
- aglioでHTML化した例
-
Attributeを使った例
- attributeを使うとaglioは自動的にjson shcema化してくれる
- コマンド例：
aglio -i user_api.md -o user_api.html
api-blueprint-previewプラグイン
- https://atom.io/packages/api-blueprint-preview
- aglioのプレビューを見ながらAPI Blueprintを編集できるAtomプラグイン
- こんな感じ https://gyazo.com/148988c30c0709abc6375a6a694699f8
- またlinter-api-blueprintというAtomプラグインを入れればリアルタイムにlintをかけてくれる
できればAPIドキュメントはみんながみれるサーバーにおきたい。でもそれを管理するの面倒…
Apiary(エイピエリ)
- https://apiary.io/
- APIドキュメントホスティングサービス
- ドキュメントが公開されてもいいなら無料
- 公開範囲をクローズドにしたいなら有料
- $99/month for 10 users
- 例： http://docs.user134.apiary.io/
- もちろんエディタ上からAPI Blueprintを書ける
- またモックサーバもついている
- 例： http://private-6de55-user134.apiary-mock.com/users/1
モックサーバー、ローカルでもちょっとほしい
api-mock
- https://github.com/localmed/api-mock
- API Blueprintの内容をもとにモックサーバーをたちあげてくれるツール
% api-mock user_api.md
info: Enabled Cross-Origin-Resource-Sharing (CORS)
info: Allow-Origin: *
info: Allow-Methods: GET, PUT, POST, PATCH, DELETE, TRACE, OPTIONS
info: Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization, Referer, Prefer
info: Listening on port 3000
% curl http://localhost:3000/users/1
{
"name" : "John",
"age" : 20,
"admin" : true
}
でもAPIドキュメントをしっかり書いても、しばらくしたら実装と乖離してしまう恐れが…
Dredd
- https://github.com/apiaryio/dredd
- API Blueprintをもとに実装をテストしてくれる
- .dredd.ymlにAPIエンドポイントを設定
- dreddはそのエンドポイントに対してAPI Blueprintで定義されたAPIリクエストをなげ、レスポンス内容がAPI Blueprintで定義された内容と合っているかをテスト
まとめ
- API Blueprintを使えば、人が読み書きしやすいAPIドキュメントが簡単につくれる。
- aglioを使えばさらに見やすいドキュメントになる。
- 書く場合はAtomプラグインを使うと書きやすい。
- Swaggerのように高機能でないが、さくっとドキュメントを作りたい場合はおすすめです。