GolangでAPIドキュメント自動生成

GolangでAPIドキュメント自動生成 2017/11/17 飯野雅希

APIドキュメント書いてますか？

APIドキュメントは書くのが大変 • Host • Path • HTTPメソッド • Request Header,
Body • Query Parameter • Response Status Code • Response Header, Body • etc...

書き手と読み手が違う • 書くのはサーバーエンジニア • 読むのはフロント・クライアントエンジニア

APIドキュメンテーションツール • Swagger • apiblueprint

API Blueprint • Markdownを使って定義を書く ◦ 拡張子は.apib • Markdownそのままでも読みやすい

API Blueprint • 基本情報 ◦ タイトル ◦ ホスト • グループ
• endopoint情報 ◦ HTTPメソッド ◦ endpoint ◦ リクエスト ◦ パラメータ ◦ レスポンス

読みやすく高機能

だけど、手書きで管理し続けるのは大変

ドキュメントを自動生成しよう要件 • Golangでコード書いたらapiblueprintでドキュメント自動生成 • apibファイルだとviewerがいるので、HTMLに変換

apiblueprint生成 test2doc：https://github.com/adams-sarah/test2doc • GolangのPackage • Star 236 • Unitテストと組み合わせると自動でAPIドキュメントを生成してくれる

test2doc

HTMLに変換 Gulpスクリプトで変換 https://storage.googleapis.com/iino-test-api-doc-test/out.html

所感 • 自動で生成されるのでコードとドキュメントの乖離がなくなる • Go lint/vet でタイポも防げる • 楽できる

Masaki Iino