http://d-cube.connpass.com/event/43057/ にて発表した内容です

1. こんなに使える！今どきの
APIドキュメンテーションツール
2016/10/25 権藤 尚樹

2. 自己紹介
● 権藤 尚樹
● ビズリーチ
● スタンバイ事業部
● バックエンドエンジニア
● Scala書いてます
● 一人旅が好きです

3. 日本最大級の求人検索エンジン「スタンバイ」

4. いろいろ検索してみてください

5. スタンバイの開発はマイクロサービス化
● 複数のAPIに分けている
● チームも細かく分かれている
● 分業化も進めている

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

7. APIドキュメントは書くことが多い
● Host
● Path
● HTTPメソッド(GET, POST, PUT, DELETE, ...)
● Request Header, Body
● Query Parameter
● Response Status Code
● Respose Header, Body
● Authrozation, Authentication
● etc...

8. APIドキュメントは読みやすく
● 作るのはサーバーサイドエンジニア
● 読む人は様々
○ フロントエンドエンジニア
○ ネイティブアプリエンジニア
○ マイクロサービスの場合、他チームのサーバーサイドエンジニア
● フォーマットを統一する必要がある
○ 表形式では限界がある

9. JSON Schemaについて少し

10. JSON Schemaとは
● JSONの型をJSONで定義する
● 細かい定義が可能
● ライブラリやバリデーションが充実している

11. JSON SchemaではAPIドキュメントは書きづらい
● あくまでJSONを定義するためのフォーマット
● APIドキュメントを書くために作られたものではない
● (個人的には)そもそもJSONを書きたくない！
● アプリケーションの開発時には使える
○ 覚えることは少ない
○ 各種バリデーション
○ モデルのGenerate

12. APIドキュメンテーションツール

13. APIドキュメンテーションツール
1. Swagger
1.1. Swagger Specification
1.2. Swagger UI
1.3. Swagger Editor
1.4. Swagger Core
2. API Blueprint
2.1. Specification
2.2. aglio

14. Swagger
● Swagger Specという定義ファイルで管理
● 歴史は古く、コミュニティ規模は大きい
● Open API Initiative というREST APIの標準化を推進する団体ができた
○ ツールとしてswaggerを使っている

15. Swagger Specification
● JSON or YAMLで定義
○ ver2.0からYAMLに対応
● schemaの部分は、JSON Schema Draft4を
ベースとしている
● GFM(Github Flavored Markdown)が使える
● モデルはdefinitionで分割可能
● 詳細はこちら
○ http://swagger.io/specification/

16. Swagger Specification
● 全体の情報
○ swaggerのバージョン
○ アプリケーションの情報
○ ホスト
○ パス
○ プロトコル
○ Mime Type

17. Swagger Specification(paths)
● endpointごとの情報
○ HTTPメソッド
○ 説明
○ リクエストパラメータ
○ レスポンス

18. Swagger Specification(definitions)
● モデルの情報
○ メンバ名
○ 型
○ 説明
○ 必須かどうか
● JSON Schemaとほぼ同じ
● $ref属性で分割可能

19. Swagger UI
● Specをもとにドキュメント化
● デモサイト: http://petstore.swagger.io/
● インタラクティブなドキュメントが特徴
● サーバーを立てれば、ブラウザ上でリクエスト
を送ったりできる
● 実態は静的HTML + jQuery
○ カスタマイズもできる

20. Swagger Core
● プロダクトコードから自動生成する
● 基本的にはコメントやアノテーションをつける
タイプが多い
● javadocのようなイメージ
● 様々な言語のフレームワークで対応

21. Swagger Editor
● specをブラウザ上で編集できるツール
● デモサイト: http://editor.swagger.io
● 実際にリクエストを送りながら編集ができる
● ローカルにインストールもできるが、 Web上
のもので事足りる

22. Swagger Codegen
● 定義ファイルからソースコードを生成
○ モックサーバーのソースコードを作れる
○ Client側のモデルのソースコードを作れる
● 様々な言語のフレームワークに対応
● Swagger Editor画面の左上にもついてる

23. Swaggerの良い点
● コードアノテーションで生成できる
○ ソースコードとドキュメントの乖離がない！
○ 他のドキュメンテーションツールにない強み
○ テスト環境を用意する必要もない
● Swagger UIのインタラクティブドキュメントは便利
● 高機能
○ swaggerの各種ツールが充実している
● 各種言語・Webフレームワークの対応が手厚い
● 外部ツールも対応している
○ Postman
○ Amazon API Gateway

24. Swaggerのイマイチと感じる点
● Swagger UIが少し使いづらい
○ インタラクティブに動かすには Webサーバーが必要
○ カスタマイズが必要なケースもある
○ API Blueprintのaglioと比べると見た目が ...
● アノテーションは賛否両論
○ モデルのClassがきちんと定義されている必要がある
○ コードがアノテーションだらけになるため、見づらくなる
○ 各フレームワークのバージョンと対応状況に注意

25. Play2(scala)のSwagger Core
● 別プロジェクトで動いている
○ https://github.com/swagger-api/swagger-play
● 公式のものは残念ながらplay2.4まで対応、2.5は対応中
● (個人的には)ちょっと触った限り、少し面倒なところがある
○ Enum等のカスタムクラスの変換が難しそう
○ 別途annotationを加えればいけるが、記述量は多くなる

26. API Blueprint

27. ● Markdownを使って定義を書く
○ 拡張子は.apib
● Markdownそのままでも読みやすい
○ aglioを使うとさらに見やすくなる
● 専用のエディターはないが、Atomエディタのプラグインあり
○ https://atom.io/packages/api-blueprint-preview
API Blueprint

28. Specification
● 基本情報
○ タイトル
○ ホスト
● グループ
○ swaggerでいうtags
● 各endpointの処理
○ HTTPメソッド
○ endpoint
○ リクエスト
○ パラメータ
○ レスポンス

29. Specification
● Data Structuresでモデルを定義
○ swaggerでいうdefinitions
● メンバの情報は一行で記述する
○ メンバ名
○ サンプル値
○ 型
○ 説明

30. aglio
● API BlueprintをHTMLドキュメントに変換
● とても見やすい
● JSON Schemaを出力してくれる

31. こんな感じに出力してくれます

32. JSON Schemaも出してくれる

33. API Blueprintの良い点
● Markdownだけで直感的に書ける
● 自由に書きやすい
● シンプルにまとまっており、使いやすい
● aglioのHTMLドキュメントは素晴らしい

34. API Blueprintのイマイチだと思う点
● Swaggerほど高機能ではない
○ コードアノテーションのような機能はない
● 細かいスキーマの定義ができない
○ JSON Schemaでいうところのmaxlength, minlength, patternなど
○ コメントとして書くことである程度対応はできる

35. ドキュメントが正しいか確認する

36. Specファイルをもとにテストができる
● ドキュメントどおりの実装になっているか確認できる
● レビュー時に誤りに気づきやすい
● レビューアの負担が減る

37. 1. Swagger Test Template
2. Dredd
テストツール

38. Swagger Test Template
● SpecファイルからJavascriptのテストコードを
自動生成して実行
● Swagger Nodeの機能に組み込まれている

39. Swagger Nodeについて少し
● https://github.com/swagger-api/swagger-node
● Node.jsだけで一通り使えるようにしたもの
● 基本的なライフサイクル
○ specを書く
○ APIを実装する
○ テストコードを自動生成
○ テスト実行
● API Design First的な開発に向いている

40. Swagger Test Templateを使ってみて
● 導入はすぐにできた
○ https://github.com/swagger-api/swagger-node
○ http://apigee.com/about/blog/developer/swagger-test-templates-test-your-apis
● Specが増えるに連れ、運用面で障害になった
● リクエストパラメータを指定できない
● 自動生成とはいえ、テストコードを毎回作らないといけない
○ 共通の定義が変わると全部作り直す必要がある

41. Dredd
● apiary.ioが提供しているテストフレームワーク
● API Blueprintとswaggerのspecファイルを実行可能
● テストの設定ファイルをyamlで管理
● 各種CIツールにも対応

42. Dreddの良いところ
● テスト結果がわかりやすい
○ コンソール上の情報でも十分わかる
○ 特にエラー時に役に立つ
○ ログレベルも変更可能
● リクエストパラメータを指定可能
○ sample値を指定する必要はあるが、それだけで済む
● テストするendpointを指定可能
○ 設定yamlのonlyに配列で指定可能
● hook処理を追加すれば細かい処理が可能

43. hookとは
● テストに前処理・後処理を加えることができる
○ beforeAll, afterAll
○ beforeEach, afterEach
● 特定のendpointに対してのみ追加することできる
○ before, After
● 用途は様々
○ DBのレコードの初期化・掃除
○ 認証・認可
○ 個別のテスト
● いくつかの言語で書ける
○ Go, Node.js, Perl, PHP, Python, Ruby

44. まとめ

45. ● 学習コストはどちらも同じくらい
○ yamlを書くかmarkdownを書くかアノテーションを書くかの違いぐらい
● ドキュメント重視ならAPI Blueprintがおすすめ
● 定義を細かく書くならSwagger SpecをYAMLで
● 厳格に管理するならSwagger Coreのアノテーションで
ドキュメンテーション編

46. テスト編
● テストを実行するならDreddがおすすめ
○ さらに言えば、Dreddを採用するつもりなら API Blueprintのほうが良い
● テストを実行しないという選択肢もある
○ レビューや運用でカバーする

47. プロダクトやチームにあった方法を用いる
● 導入の際は開発メンバーでよく話し合うこと
○ やること、やらないことを決める
● 開発の障害にならないように進めること
○ テスト環境を揃えるのは思ったよりも大変
○ ドキュメントだけで十分ならば、レビューをしっかりやるのでも良いと思う
● 途中でツールを変えるのは大変
○ 相互変換するライブラリもあるが、完璧ではない
○ 両方覚えるのは大変
● テストを過信しないこと
○ オプショナルの項目が増えてもわからないこともある。レビューはしっかりと

48. 参考にしたサイト
● APIドキュメントを支える技術
○ http://qiita.com/taizo/items/5a969ace57394a2d5b4a
● API Meetup Tokyo #15 〜OpenAPI Specification (Swagger)特集〜の勉強会に
参加してきた
○ http://tsuyoshi-nakamura.hatenablog.com/entry/2016/07/25/114347
● API Blueprintとその周辺ツール
○ http://qiita.com/sheepland/items/b4a0d03941f2e3cd8eaa

49. サンプルコード置いてます
● https://github.com/n-gondo123/api-doc-example

50. おまけ

51. RAMLも面白そう
● 割と新しめのAPIドキュメンテーションツール
● yamlで記述する
● swaggerと似ている
● 「swagger vs api blueprint vs raml」で検索すると面白い記事が見つかる

52. ご清聴ありがとうございました。