Diese Präsentation wurde erfolgreich gemeldet.
Wir verwenden Ihre LinkedIn Profilangaben und Informationen zu Ihren Aktivitäten, um Anzeigen zu personalisieren und Ihnen relevantere Inhalte anzuzeigen. Sie können Ihre Anzeigeneinstellungen jederzeit ändern.

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

18.331 Aufrufe

Veröffentlicht am

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

Veröffentlicht in: Ingenieurwesen
  • Sex in your area is here: ❶❶❶ http://bit.ly/39pMlLF ❶❶❶
       Antworten 
    Sind Sie sicher, dass Sie …  Ja  Nein
    Ihre Nachricht erscheint hier
  • Dating for everyone is here: ❤❤❤ http://bit.ly/39pMlLF ❤❤❤
       Antworten 
    Sind Sie sicher, dass Sie …  Ja  Nein
    Ihre Nachricht erscheint hier

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

  1. 1. こんなに使える!今どきの APIドキュメンテーションツール 2016/10/25 権藤 尚樹
  2. 2. 自己紹介 ● 権藤 尚樹 ● ビズリーチ ● スタンバイ事業部 ● バックエンドエンジニア ● Scala書いてます ● 一人旅が好きです
  3. 3. 日本最大級の求人検索エンジン「スタンバイ」
  4. 4. いろいろ検索してみてください
  5. 5. スタンバイの開発はマイクロサービス化 ● 複数のAPIに分けている ● チームも細かく分かれている ● 分業化も進めている
  6. 6. APIドキュメント書いてますか?
  7. 7. APIドキュメントは書くことが多い ● Host ● Path ● HTTPメソッド(GET, POST, PUT, DELETE, ...) ● Request Header, Body ● Query Parameter ● Response Status Code ● Respose Header, Body ● Authrozation, Authentication ● etc...
  8. 8. APIドキュメントは読みやすく ● 作るのはサーバーサイドエンジニア ● 読む人は様々 ○ フロントエンドエンジニア ○ ネイティブアプリエンジニア ○ マイクロサービスの場合、他チームのサーバーサイドエンジニア ● フォーマットを統一する必要がある ○ 表形式では限界がある
  9. 9. JSON Schemaについて少し
  10. 10. JSON Schemaとは ● JSONの型をJSONで定義する ● 細かい定義が可能 ● ライブラリやバリデーションが充実している
  11. 11. JSON SchemaではAPIドキュメントは書きづらい ● あくまでJSONを定義するためのフォーマット ● APIドキュメントを書くために作られたものではない ● (個人的には)そもそもJSONを書きたくない! ● アプリケーションの開発時には使える ○ 覚えることは少ない ○ 各種バリデーション ○ モデルのGenerate
  12. 12. APIドキュメンテーションツール
  13. 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. 14. Swagger ● Swagger Specという定義ファイルで管理 ● 歴史は古く、コミュニティ規模は大きい ● Open API Initiative というREST APIの標準化を推進する団体ができた ○ ツールとしてswaggerを使っている
  15. 15. Swagger Specification ● JSON or YAMLで定義 ○ ver2.0からYAMLに対応 ● schemaの部分は、JSON Schema Draft4を ベースとしている ● GFM(Github Flavored Markdown)が使える ● モデルはdefinitionで分割可能 ● 詳細はこちら ○ http://swagger.io/specification/
  16. 16. Swagger Specification ● 全体の情報 ○ swaggerのバージョン ○ アプリケーションの情報 ○ ホスト ○ パス ○ プロトコル ○ Mime Type
  17. 17. Swagger Specification(paths) ● endpointごとの情報 ○ HTTPメソッド ○ 説明 ○ リクエストパラメータ ○ レスポンス
  18. 18. Swagger Specification(definitions) ● モデルの情報 ○ メンバ名 ○ 型 ○ 説明 ○ 必須かどうか ● JSON Schemaとほぼ同じ ● $ref属性で分割可能
  19. 19. Swagger UI ● Specをもとにドキュメント化 ● デモサイト: http://petstore.swagger.io/ ● インタラクティブなドキュメントが特徴 ● サーバーを立てれば、ブラウザ上でリクエスト を送ったりできる ● 実態は静的HTML + jQuery ○ カスタマイズもできる
  20. 20. Swagger Core ● プロダクトコードから自動生成する ● 基本的にはコメントやアノテーションをつける タイプが多い ● javadocのようなイメージ ● 様々な言語のフレームワークで対応
  21. 21. Swagger Editor ● specをブラウザ上で編集できるツール ● デモサイト: http://editor.swagger.io ● 実際にリクエストを送りながら編集ができる ● ローカルにインストールもできるが、 Web上 のもので事足りる
  22. 22. Swagger Codegen ● 定義ファイルからソースコードを生成 ○ モックサーバーのソースコードを作れる ○ Client側のモデルのソースコードを作れる ● 様々な言語のフレームワークに対応 ● Swagger Editor画面の左上にもついてる
  23. 23. Swaggerの良い点 ● コードアノテーションで生成できる ○ ソースコードとドキュメントの乖離がない! ○ 他のドキュメンテーションツールにない強み ○ テスト環境を用意する必要もない ● Swagger UIのインタラクティブドキュメントは便利 ● 高機能 ○ swaggerの各種ツールが充実している ● 各種言語・Webフレームワークの対応が手厚い ● 外部ツールも対応している ○ Postman ○ Amazon API Gateway
  24. 24. Swaggerのイマイチと感じる点 ● Swagger UIが少し使いづらい ○ インタラクティブに動かすには Webサーバーが必要 ○ カスタマイズが必要なケースもある ○ API Blueprintのaglioと比べると見た目が ... ● アノテーションは賛否両論 ○ モデルのClassがきちんと定義されている必要がある ○ コードがアノテーションだらけになるため、見づらくなる ○ 各フレームワークのバージョンと対応状況に注意
  25. 25. Play2(scala)のSwagger Core ● 別プロジェクトで動いている ○ https://github.com/swagger-api/swagger-play ● 公式のものは残念ながらplay2.4まで対応、2.5は対応中 ● (個人的には)ちょっと触った限り、少し面倒なところがある ○ Enum等のカスタムクラスの変換が難しそう ○ 別途annotationを加えればいけるが、記述量は多くなる
  26. 26. API Blueprint
  27. 27. ● Markdownを使って定義を書く ○ 拡張子は.apib ● Markdownそのままでも読みやすい ○ aglioを使うとさらに見やすくなる ● 専用のエディターはないが、Atomエディタのプラグインあり ○ https://atom.io/packages/api-blueprint-preview API Blueprint
  28. 28. Specification ● 基本情報 ○ タイトル ○ ホスト ● グループ ○ swaggerでいうtags ● 各endpointの処理 ○ HTTPメソッド ○ endpoint ○ リクエスト ○ パラメータ ○ レスポンス
  29. 29. Specification ● Data Structuresでモデルを定義 ○ swaggerでいうdefinitions ● メンバの情報は一行で記述する ○ メンバ名 ○ サンプル値 ○ 型 ○ 説明
  30. 30. aglio ● API BlueprintをHTMLドキュメントに変換 ● とても見やすい ● JSON Schemaを出力してくれる
  31. 31. こんな感じに出力してくれます
  32. 32. JSON Schemaも出してくれる
  33. 33. API Blueprintの良い点 ● Markdownだけで直感的に書ける ● 自由に書きやすい ● シンプルにまとまっており、使いやすい ● aglioのHTMLドキュメントは素晴らしい
  34. 34. API Blueprintのイマイチだと思う点 ● Swaggerほど高機能ではない ○ コードアノテーションのような機能はない ● 細かいスキーマの定義ができない ○ JSON Schemaでいうところのmaxlength, minlength, patternなど ○ コメントとして書くことである程度対応はできる
  35. 35. ドキュメントが正しいか確認する
  36. 36. Specファイルをもとにテストができる ● ドキュメントどおりの実装になっているか確認できる ● レビュー時に誤りに気づきやすい ● レビューアの負担が減る
  37. 37. 1. Swagger Test Template 2. Dredd テストツール
  38. 38. Swagger Test Template ● SpecファイルからJavascriptのテストコードを 自動生成して実行 ● Swagger Nodeの機能に組み込まれている
  39. 39. Swagger Nodeについて少し ● https://github.com/swagger-api/swagger-node ● Node.jsだけで一通り使えるようにしたもの ● 基本的なライフサイクル ○ specを書く ○ APIを実装する ○ テストコードを自動生成 ○ テスト実行 ● API Design First的な開発に向いている
  40. 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. 41. Dredd ● apiary.ioが提供しているテストフレームワーク ● API Blueprintとswaggerのspecファイルを実行可能 ● テストの設定ファイルをyamlで管理 ● 各種CIツールにも対応
  42. 42. Dreddの良いところ ● テスト結果がわかりやすい ○ コンソール上の情報でも十分わかる ○ 特にエラー時に役に立つ ○ ログレベルも変更可能 ● リクエストパラメータを指定可能 ○ sample値を指定する必要はあるが、それだけで済む ● テストするendpointを指定可能 ○ 設定yamlのonlyに配列で指定可能 ● hook処理を追加すれば細かい処理が可能
  43. 43. hookとは ● テストに前処理・後処理を加えることができる ○ beforeAll, afterAll ○ beforeEach, afterEach ● 特定のendpointに対してのみ追加することできる ○ before, After ● 用途は様々 ○ DBのレコードの初期化・掃除 ○ 認証・認可 ○ 個別のテスト ● いくつかの言語で書ける ○ Go, Node.js, Perl, PHP, Python, Ruby
  44. 44. まとめ
  45. 45. ● 学習コストはどちらも同じくらい ○ yamlを書くかmarkdownを書くかアノテーションを書くかの違いぐらい ● ドキュメント重視ならAPI Blueprintがおすすめ ● 定義を細かく書くならSwagger SpecをYAMLで ● 厳格に管理するならSwagger Coreのアノテーションで ドキュメンテーション編
  46. 46. テスト編 ● テストを実行するならDreddがおすすめ ○ さらに言えば、Dreddを採用するつもりなら API Blueprintのほうが良い ● テストを実行しないという選択肢もある ○ レビューや運用でカバーする
  47. 47. プロダクトやチームにあった方法を用いる ● 導入の際は開発メンバーでよく話し合うこと ○ やること、やらないことを決める ● 開発の障害にならないように進めること ○ テスト環境を揃えるのは思ったよりも大変 ○ ドキュメントだけで十分ならば、レビューをしっかりやるのでも良いと思う ● 途中でツールを変えるのは大変 ○ 相互変換するライブラリもあるが、完璧ではない ○ 両方覚えるのは大変 ● テストを過信しないこと ○ オプショナルの項目が増えてもわからないこともある。レビューはしっかりと
  48. 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. 49. サンプルコード置いてます ● https://github.com/n-gondo123/api-doc-example
  50. 50. おまけ
  51. 51. RAMLも面白そう ● 割と新しめのAPIドキュメンテーションツール ● yamlで記述する ● swaggerと似ている ● 「swagger vs api blueprint vs raml」で検索すると面白い記事が見つかる
  52. 52. ご清聴ありがとうございました。

×