こんなに使える！今どきのAPIドキュメンテーションツール

2016/10/25 権藤 尚樹

自己紹介

● 権藤 尚樹

● ビズリーチ

● スタンバイ事業部

● バックエンドエンジニア

● Scala書いてます

● 一人旅が好きです

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

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

スタンバイの開発はマイクロサービス化

● 複数のAPIに分けている

● チームも細かく分かれている

● 分業化も進めている

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

APIドキュメントは書くことが多い

● Host● Path● HTTPメソッド(GET, POST, PUT, DELETE, ...)● Request Header, Body● Query Parameter● Response Status Code● Respose Header, Body● Authrozation, Authentication● etc...

APIドキュメントは読みやすく

● 作るのはサーバーサイドエンジニア

● 読む人は様々○ フロントエンドエンジニア

○ ネイティブアプリエンジニア

○ マイクロサービスの場合、他チームのサーバーサイドエンジニア

● フォーマットを統一する必要がある○ 表形式では限界がある

JSON Schemaについて少し

JSON Schemaとは

● JSONの型をJSONで定義する

● 細かい定義が可能

● ライブラリやバリデーションが充実している

JSON SchemaではAPIドキュメントは書きづらい

● あくまでJSONを定義するためのフォーマット

● APIドキュメントを書くために作られたものではない

● (個人的には)そもそもJSONを書きたくない！

● アプリケーションの開発時には使える○ 覚えることは少ない

○ 各種バリデーション

○ モデルのGenerate

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

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

1. Swagger1.1. Swagger Specification1.2. Swagger UI1.3. Swagger Editor1.4. Swagger Core

2. API Blueprint2.1. Specification2.2. aglio

Swagger● Swagger Specという定義ファイルで管理

● 歴史は古く、コミュニティ規模は大きい

● Open API Initiative というREST APIの標準化を推進する団体ができた○ ツールとしてswaggerを使っている

Swagger Specification● JSON or YAMLで定義

○ ver2.0からYAMLに対応

● schemaの部分は、JSON Schema Draft4をベースとしている

● GFM(Github Flavored Markdown)が使える

● モデルはdefinitionで分割可能

● 詳細はこちら

○ http://swagger.io/specification/

Swagger Specification● 全体の情報

○ swaggerのバージョン

○ アプリケーションの情報

○ ホスト

○ パス

○ プロトコル

○ Mime Type

Swagger Specification(paths)● endpointごとの情報

○ HTTPメソッド

○ 説明

○ リクエストパラメータ

○ レスポンス

Swagger Specification(definitions)● モデルの情報

○ メンバ名

○ 型

○ 説明

○ 必須かどうか

● JSON Schemaとほぼ同じ

● $ref属性で分割可能

Swagger UI● Specをもとにドキュメント化

● デモサイト: http://petstore.swagger.io/● インタラクティブなドキュメントが特徴

● サーバーを立てれば、ブラウザ上でリクエスト

を送ったりできる

● 実態は静的HTML + jQuery○ カスタマイズもできる

Swagger Core● プロダクトコードから自動生成する

● 基本的にはコメントやアノテーションをつける

タイプが多い

● javadocのようなイメージ

● 様々な言語のフレームワークで対応

Swagger Editor● specをブラウザ上で編集できるツール

● デモサイト: http://editor.swagger.io● 実際にリクエストを送りながら編集ができる

● ローカルにインストールもできるが、 Web上のもので事足りる

Swagger Codegen● 定義ファイルからソースコードを生成

○ モックサーバーのソースコードを作れる

○ Client側のモデルのソースコードを作れる

● 様々な言語のフレームワークに対応

● Swagger Editor画面の左上にもついてる

Swaggerの良い点

● コードアノテーションで生成できる○ ソースコードとドキュメントの乖離がない！

○ 他のドキュメンテーションツールにない強み

○ テスト環境を用意する必要もない

● Swagger UIのインタラクティブドキュメントは便利

● 高機能○ swaggerの各種ツールが充実している

● 各種言語・Webフレームワークの対応が手厚い

● 外部ツールも対応している○ Postman○ Amazon API Gateway

Swaggerのイマイチと感じる点

● Swagger UIが少し使いづらい○ インタラクティブに動かすには Webサーバーが必要

○ カスタマイズが必要なケースもある

○ API Blueprintのaglioと比べると見た目が ...

● アノテーションは賛否両論○ モデルのClassがきちんと定義されている必要がある

○ コードがアノテーションだらけになるため、見づらくなる

○ 各フレームワークのバージョンと対応状況に注意

Play2(scala)のSwagger Core● 別プロジェクトで動いている

○ https://github.com/swagger-api/swagger-play

● 公式のものは残念ながらplay2.4まで対応、2.5は対応中

● (個人的には)ちょっと触った限り、少し面倒なところがある

○ Enum等のカスタムクラスの変換が難しそう

○ 別途annotationを加えればいけるが、記述量は多くなる

API Blueprint

● Markdownを使って定義を書く○ 拡張子は.apib

● Markdownそのままでも読みやすい○ aglioを使うとさらに見やすくなる

● 専用のエディターはないが、Atomエディタのプラグインあり○ https://atom.io/packages/api-blueprint-preview

API Blueprint

Specification● 基本情報

○ タイトル

○ ホスト

● グループ

○ swaggerでいうtags● 各endpointの処理

○ HTTPメソッド

○ endpoint○ リクエスト

○ パラメータ

○ レスポンス

Specification● Data Structuresでモデルを定義

○ swaggerでいうdefinitions● メンバの情報は一行で記述する

○ メンバ名

○ サンプル値

○ 型

○ 説明

aglio● API BlueprintをHTMLドキュメントに変換

● とても見やすい

● JSON Schemaを出力してくれる

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

JSON Schemaも出してくれる

API Blueprintの良い点

● Markdownだけで直感的に書ける

● 自由に書きやすい

● シンプルにまとまっており、使いやすい

● aglioのHTMLドキュメントは素晴らしい

API Blueprintのイマイチだと思う点

● Swaggerほど高機能ではない○ コードアノテーションのような機能はない

● 細かいスキーマの定義ができない○ JSON Schemaでいうところのmaxlength, minlength, patternなど

○ コメントとして書くことである程度対応はできる

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

Specファイルをもとにテストができる

● ドキュメントどおりの実装になっているか確認できる

● レビュー時に誤りに気づきやすい

● レビューアの負担が減る

1. Swagger Test Template2. Dredd

テストツール

Swagger Test Template● SpecファイルからJavascriptのテストコードを

自動生成して実行

● Swagger Nodeの機能に組み込まれている

Swagger Nodeについて少し

● https://github.com/swagger-api/swagger-node● Node.jsだけで一通り使えるようにしたもの

● 基本的なライフサイクル

○ specを書く

○ APIを実装する

○ テストコードを自動生成

○ テスト実行

● API Design First的な開発に向いている

Swagger Test Templateを使ってみて

● 導入はすぐにできた○ https://github.com/swagger-api/swagger-node○ http://apigee.com/about/blog/developer/swagger-test-templates-test-your-apis

● Specが増えるに連れ、運用面で障害になった

● リクエストパラメータを指定できない

● 自動生成とはいえ、テストコードを毎回作らないといけない○ 共通の定義が変わると全部作り直す必要がある

Dredd● apiary.ioが提供しているテストフレームワーク

● API Blueprintとswaggerのspecファイルを実行可能

● テストの設定ファイルをyamlで管理

● 各種CIツールにも対応

Dreddの良いところ

● テスト結果がわかりやすい○ コンソール上の情報でも十分わかる

○ 特にエラー時に役に立つ

○ ログレベルも変更可能

● リクエストパラメータを指定可能○ sample値を指定する必要はあるが、それだけで済む

● テストするendpointを指定可能○ 設定yamlのonlyに配列で指定可能

● hook処理を追加すれば細かい処理が可能

hookとは

● テストに前処理・後処理を加えることができる○ beforeAll, afterAll○ beforeEach, afterEach

● 特定のendpointに対してのみ追加することできる○ before, After

● 用途は様々○ DBのレコードの初期化・掃除

○ 認証・認可

○ 個別のテスト

● いくつかの言語で書ける○ Go, Node.js, Perl, PHP, Python, Ruby

まとめ

● 学習コストはどちらも同じくらい○ yamlを書くかmarkdownを書くかアノテーションを書くかの違いぐらい

● ドキュメント重視ならAPI Blueprintがおすすめ

● 定義を細かく書くならSwagger SpecをYAMLで● 厳格に管理するならSwagger Coreのアノテーションで

ドキュメンテーション編

テスト編

● テストを実行するならDreddがおすすめ○ さらに言えば、Dreddを採用するつもりならAPI Blueprintのほうが良い

● テストを実行しないという選択肢もある○ レビューや運用でカバーする

プロダクトやチームにあった方法を用いる

● 導入の際は開発メンバーでよく話し合うこと○ やること、やらないことを決める

● 開発の障害にならないように進めること○ テスト環境を揃えるのは思ったよりも大変

○ ドキュメントだけで十分ならば、レビューをしっかりやるのでも良いと思う

● 途中でツールを変えるのは大変○ 相互変換するライブラリもあるが、完璧ではない

○ 両方覚えるのは大変

● テストを過信しないこと○ オプショナルの項目が増えてもわからないこともある。レビューはしっかりと

参考にしたサイト

● 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

サンプルコード置いてます

● https://github.com/n-gondo123/api-doc-example

おまけ

RAMLも面白そう

● 割と新しめのAPIドキュメンテーションツール

● yamlで記述する

● swaggerと似ている

● 「swagger vs api blueprint vs raml」で検索すると面白い記事が見つかる

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