Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Swaggerによる モデルファースト!? API開発 よもやま話 by TIS株式会社 ⼩⻄ 啓介
⾃⼰紹介 ⼩⻄ 啓介 (KONISHI Keisuke) •  SIerに勤める12年⽬の現場エンジニア •  昔 –  XML DBの普及を夢⾒てた –  XML DB プログラミングコンテストで最優秀賞 •  最近 –  Startup W...
Swaggerとの出会い
Swaggerとの出会い •  昨年、スマホアプリ向けのAPI開発で  API仕様をExcelで書きたくなかった – 漏れのないフォーマットが作れない – 仕様書からAPIスタブを⽣成したい •  「Swagger」を発⾒ – 佐々⽊拓郎さんの...
パイロットプロジェクトの概要
お断り 現在進⾏中の案件の為、業務的な 話や実際に作成したAPI仕様などは、 ご紹介できません。 その代わり? サンプルとして「Redmine API」のSwagger定義を作成しました。 → 完成したらGitHubに上げます。(たぶん)
パイロットプロジェクトの概要 •  期間は３か⽉ •  ⽬的 –  「使われるAPI」を⽬指す –  API利⽤者に事前公開しフィードバックを得る •  やること –  ドラフトAPI仕様の策定 –  サンドボックスの構築 •  進め⽅ –  ...
パイロットプロジェクトの概要 •  サンドボックスの技術要素 – サーバ(API-GW)：Apigee Edge (all in one) – バックエンド：Node.js – データストア：Apache UserGrid (NoSQL) • ...
フェーズ１：API⾻格検討 •  最初はExcel等で整理(いきなりSwaggerは難しい) – 業務機能洗い出し – リソース抽出 – 項⽬名の名寄せ、英字検討 •  Swaggerは項⽬名だけ書く(詳細まで書かない) – Path – Op...
フェーズ２：サンドボックス構築 •  ⾻格が固まったら詳細記述 – 型(type, format ,pattern(正規表現)) – 必須、最⼩値、最⼤値,ENUM – description等の説明の充実 – セキュリティ(OAuth関連) ...
プロジェクトで気が付いたこと (swagger関連のみ)
Swagger Editorについて(1/2) •  とても使いやすい、わけではない – ⼊⼒補助はあるが、賢くはない – 構⽂エラーを取るのは⼀苦労 •  慣れないと指摘内容がわかりにくい – 左右の画⾯移動が⼀⽅向のみ (左→右:NG) •...
Swagger Editorについて(2/2)
Swagger UIについて(1/2) •  カスタマイズが必要 –  認証関係、バグパッチ対応、⽇本語化 –  修正は、基本index.html、jQueryでOK •  表⽰されるレスポンスは、加⼯されている –  CORSのXHRでのエラ...
Swagger UIについて(2/2)
Swagger Nodeについて •  Swagger定義でフォーマットValidation、 単項⽬Validationしてくれるのはとても便利 •  リクエストだけでなく、レスポンスも Validation可能、ただ、正常系もエラー系も す...
Swagger 仕様について(1/6) •  全体の構成が分かりにくい – リクエストとレスポンスが⾮対称 •  リクエストは、URIで送る情報、headerで送る情 報、bodyで送る情報をparametersに配列で定義 •  レスポンスは...
オブジェクト 構成図 •  仕様書のObjectの 参照関係を階層 構造で定義 •  $refの参照関係を 定義 •  見えないし、分か らないですよね。。
OpenAPI Specification Visual Documentation h,p://openapi- specifica7on-visual- documenta7on.apihandy man.io/ ※誤記もあるので注意
Swagger 仕様について(4/6) •  ⼤事な部分は、JSON Schema参照 – リクエストとレスポンスの項⽬定義について、 SwaggerとJSON Schemaのリファレンスを 両⽅みないとよくわからない。 •  オブジェクトの配...
Swagger 仕様について(5/6) •  “host”パラメータは、任意 – 書かなければ、ドキュメントのホスト •  環境毎に書き換えなくていいので便利 – ただし、セキュリティ定義の(authorization uri/token ur...
Swagger 仕様について(6/6) •  レスポンスのエラー定義 – レスポンスの定義は、ステータスコード単位 – “400”で業務エラーを定義すると、業務エ ラーコード等の定義が集中してしまう – 業務エラーコードの情報をどこに書くか注意...
気が付いたこと（まとめ） •  Swagger 仕様は結構難しい •  Swagger EditorとUIで違う •  Swagger UIは、カスタマイズが必要 •  内部⽤と外部⽤でSwaggerを分けたくなる けど極⼒分けない(⽣成する)
Swagger仕様でよく悩むこと
定義の共通化について •  Swaggerを書いていると、リクエストやレ スポンス等に同⼀定義が繰り返し出てくる •  これらを共通化するのが、Referenceオブ ジェクト($ref)による参照である。 •  Swaggerの仕様では、Re...
定義の共通化について •  参照先の定義は３種類 –  Parameters Definitions •  Parameterオブジェクトを定義 –  Responses Definitions •  Responseオブジェクトを定義 –  (S...
Parameters Definitions •  参照元JSON Pointer –  #/paths/{path}/parameters/0/$ref –  #/paths/{path}/{method}/parameters/0/$ref ...
Parameters Definitions #/ parameters /{name} #/paths/{path}/parameters/0/$ref #/paths/{path}/{method}/parameters/0/$ref
Responses Definitions •  参照元(JSON Pointer) –  #/paths/{path}/{method}/responses/{StatusCode}/$ref •  参照先(JSON Pointer) – #/...
Responses Definitions #/ responses /{name} #/paths/{path}/{method}/responses/{StatusCode}/$ref
(schema) Definitions •  参照元ベースパス (Schema Object JSON Pointer) –  #/paths/{path}/parameters/0/schema –  #/paths/{path}/{meth...
(schema) Definitions #/paths/{path}/{method}/parameters/0/schema #/defini7ons/{name}
description等の説明⽂の記載 •  Swaggerは、API仕様ですので、定義だけでなく、 様々な説明書きを記載するが混乱しがちなので整 理 •  項⽬として"description"や"summary", "title"と いう項⽬...
!tle descrip!on JSON pointer GFM Editor UI アプリケーションのタ イトル 　 #/info/7tle ☓ ◯ ◯ アプリケーションの 説明 アプリケーションの全体 に関する説明は、ここ に記...
!tle descrip!on JSON pointer　（#/paths/{path}配下） GFM Editor UI リソース操作の概要 　 /{method}/summary ☓ ◯ ◯ リソース操作の説明 　 /{met...
!tle descrip!on JSON pointer　（#/paths/{path}配下） GFM Editor UI ステータスコード単位の レスポンスの説明 　 /{method}/responses/{StatusCode}/de...
Upcoming SlideShare
Loading in …5
×

Swaggerでのapi開発よもやま話

23,592 views

Published on

API Meetup Tokyo #15 〜OpenAPI Specification (Swagger)特集〜
2016-07-22（金）19:00 - 21:00

API公開に向けたパイロットPJにて、設計、実装（単項目チェック）、ドキュメント、仕様公開にSwaggerを採用した際の経験談をお話します。

Published in: Software
no profile picture user

  • Login to see the comments

Show More

Swaggerでのapi開発よもやま話

  1. 1. Swaggerによる モデルファースト!? API開発 よもやま話 by TIS株式会社 ⼩⻄ 啓介
  2. 2. ⾃⼰紹介 ⼩⻄ 啓介 (KONISHI Keisuke) •  SIerに勤める12年⽬の現場エンジニア •  昔 –  XML DBの普及を夢⾒てた –  XML DB プログラミングコンテストで最優秀賞 •  最近 –  Startup Weekend FinTechで参加チームが、優勝 •  API Meetupの運営チームに参加
  3. 3. Swaggerとの出会い
  4. 4. Swaggerとの出会い •  昨年、スマホアプリ向けのAPI開発で  API仕様をExcelで書きたくなかった – 漏れのないフォーマットが作れない – 仕様書からAPIスタブを⽣成したい •  「Swagger」を発⾒ – 佐々⽊拓郎さんのSlide –  http://www.slideshare.net/takurosasaki/swaggerapi
  5. 5. パイロットプロジェクトの概要
  6. 6. お断り 現在進⾏中の案件の為、業務的な 話や実際に作成したAPI仕様などは、 ご紹介できません。 その代わり? サンプルとして「Redmine API」のSwagger定義を作成しました。 → 完成したらGitHubに上げます。(たぶん)
  7. 7. パイロットプロジェクトの概要 •  期間は３か⽉ •  ⽬的 –  「使われるAPI」を⽬指す –  API利⽤者に事前公開しフィードバックを得る •  やること –  ドラフトAPI仕様の策定 –  サンドボックスの構築 •  進め⽅ –  モデルファースト、Swaggerを全⾯採⽤ –  外部インターフェイスに注⼒ •  既存バックエンドのことはあまり考えない
  8. 8. パイロットプロジェクトの概要 •  サンドボックスの技術要素 – サーバ(API-GW)：Apigee Edge (all in one) – バックエンド：Node.js – データストア：Apache UserGrid (NoSQL) •  Swagger関連ツール – Swagger Editer (編集) – Swagger UI (API仕様公開、試⾏呼出) – Swagger Node(A127) (API-FW , validation) – Swagger2markup (PDFでのAPI仕様公開)
  9. 9. フェーズ１：API⾻格検討 •  最初はExcel等で整理(いきなりSwaggerは難しい) – 業務機能洗い出し – リソース抽出 – 項⽬名の名寄せ、英字検討 •  Swaggerは項⽬名だけ書く(詳細まで書かない) – Path – Operation – 必須リクエストパラメータ – 正常系のレスポンス
  10. 10. フェーズ２：サンドボックス構築 •  ⾻格が固まったら詳細記述 – 型(type, format ,pattern(正規表現)) – 必須、最⼩値、最⼤値,ENUM – description等の説明の充実 – セキュリティ(OAuth関連) – 共通化定義 – エラー定義
  11. 11. プロジェクトで気が付いたこと (swagger関連のみ)
  12. 12. Swagger Editorについて(1/2) •  とても使いやすい、わけではない – ⼊⼒補助はあるが、賢くはない – 構⽂エラーを取るのは⼀苦労 •  慣れないと指摘内容がわかりにくい – 左右の画⾯移動が⼀⽅向のみ (左→右:NG) •  気が付きにくい機能 – 「Ctrl + F」を２回で置換出来る – Edit画⾯で階層で折りたためる •  Swagger UIとの互換性は考えてない！？
  13. 13. Swagger Editorについて(2/2)
  14. 14. Swagger UIについて(1/2) •  カスタマイズが必要 –  認証関係、バグパッチ対応、⽇本語化 –  修正は、基本index.html、jQueryでOK •  表⽰されるレスポンスは、加⼯されている –  CORSのXHRでのエラーは不明 –  304(Not Modified)は、200で表⽰ •  Chromeの開発画⾯を⾒たほうがいい •  表⽰されないswaggerの情報がある –  swaggerファイルも公開すべし •  ベンダー拡張、内部APIはフィルタ •  アルファベット順で必ずソートされる –  apisSorter, operationsSorterは、1.2⽤記述?
  15. 15. Swagger UIについて(2/2)
  16. 16. Swagger Nodeについて •  Swagger定義でフォーマットValidation、 単項⽬Validationしてくれるのはとても便利 •  リクエストだけでなく、レスポンスも Validation可能、ただ、正常系もエラー系も すべてValidationするのはすこし⼤変 –  additionalProperties:falseにするともっと⼤変 •  もちろん、リクエストのValidationエラーの レスポンスがレスポンスvalidationエラーに なることも
  17. 17. Swagger 仕様について(1/6) •  全体の構成が分かりにくい – リクエストとレスポンスが⾮対称 •  リクエストは、URIで送る情報、headerで送る情 報、bodyで送る情報をparametersに配列で定義 •  レスポンスは、ステータスコード、headerで受け 取る情報、bodyで受け取る情報をマップで定義 – 仕様書は、オブジェクトの参照関係のみ •  Object構成図が欲しい！
  18. 18. オブジェクト 構成図 •  仕様書のObjectの 参照関係を階層 構造で定義 •  $refの参照関係を 定義 •  見えないし、分か らないですよね。。
  19. 19. OpenAPI Specification Visual Documentation h,p://openapi- specifica7on-visual- documenta7on.apihandy man.io/ ※誤記もあるので注意
  20. 20. Swagger 仕様について(4/6) •  ⼤事な部分は、JSON Schema参照 – リクエストとレスポンスの項⽬定義について、 SwaggerとJSON Schemaのリファレンスを 両⽅みないとよくわからない。 •  オブジェクトの配列に注意 – 配列の識別⼦(“-”)とオブジェクトを別⾏に！ – 基本的にtagsとparameters、security、 allOf４つだけなので覚える！！
  21. 21. Swagger 仕様について(5/6) •  “host”パラメータは、任意 – 書かなければ、ドキュメントのホスト •  環境毎に書き換えなくていいので便利 – ただし、セキュリティ定義の(authorization uri/token uri)は絶対URLで”host”とは無関係 •  PJでは、SwaggerUIをカスタマイズして、 descriptionを含めて、全てのURLをjQueryで⾃動 的に書き換えました
  22. 22. Swagger 仕様について(6/6) •  レスポンスのエラー定義 – レスポンスの定義は、ステータスコード単位 – “400”で業務エラーを定義すると、業務エ ラーコード等の定義が集中してしまう – 業務エラーコードの情報をどこに書くか注意 •  Swaggerの外部に書くのもあり –  ただし、externalDocsは、UIでは、表⽰されないので、 descriptionにリンクを書く
  23. 23. 気が付いたこと（まとめ） •  Swagger 仕様は結構難しい •  Swagger EditorとUIで違う •  Swagger UIは、カスタマイズが必要 •  内部⽤と外部⽤でSwaggerを分けたくなる けど極⼒分けない(⽣成する)
  24. 24. Swagger仕様でよく悩むこと
  25. 25. 定義の共通化について •  Swaggerを書いていると、リクエストやレ スポンス等に同⼀定義が繰り返し出てくる •  これらを共通化するのが、Referenceオブ ジェクト($ref)による参照である。 •  Swaggerの仕様では、Referenceオブジェク トをさまざまな場所に記載できるが、少しわ かりにくいので整理する。 •  外部ファイル参照については、取り上げない。
  26. 26. 定義の共通化について •  参照先の定義は３種類 –  Parameters Definitions •  Parameterオブジェクトを定義 –  Responses Definitions •  Responseオブジェクトを定義 –  (Schema) Definitions •  Schemaオブジェクトを定義 •  Parameters,Responsesは⾃⾝参照出来ない •  DefinitionsはDefinitionsは⾃⼰参照することが出来る •  ただし、Alias的(直接$refする)な参照は⾮推奨?警告 が出る •  responseのheaderの共⽤化は、出来ない
  27. 27. Parameters Definitions •  参照元JSON Pointer –  #/paths/{path}/parameters/0/$ref –  #/paths/{path}/{method}/parameters/0/$ref •  参照先JSON Pointer – #/parameters/{name}
  28. 28. Parameters Definitions #/ parameters /{name} #/paths/{path}/parameters/0/$ref #/paths/{path}/{method}/parameters/0/$ref
  29. 29. Responses Definitions •  参照元(JSON Pointer) –  #/paths/{path}/{method}/responses/{StatusCode}/$ref •  参照先(JSON Pointer) – #/responses/{name}
  30. 30. Responses Definitions #/ responses /{name} #/paths/{path}/{method}/responses/{StatusCode}/$ref
  31. 31. (schema) Definitions •  参照元ベースパス (Schema Object JSON Pointer) –  #/paths/{path}/parameters/0/schema –  #/paths/{path}/{method}/parameters/0/schema –  #/paths/{path}/{method}/responses/{StatusCode}/schema –  ＃/parameters/{name}/schema –  ＃/responses/{name}/schema –  ＃/definitions/{name} •  参照元(JSON Pointer) –  {参照元１}/$ref –  {参照元１}/items/$ref –  {参照元１}/properties/{property}/$ref –  {参照元１}/properties/{property}/additionalProperties/$ref –  {参照元１}/properties/{property}/allOf/0/$ref •  参照先(JSON Pointer) –  #/definitions/{name}
  32. 32. (schema) Definitions #/paths/{path}/{method}/parameters/0/schema #/defini7ons/{name}
  33. 33. description等の説明⽂の記載 •  Swaggerは、API仕様ですので、定義だけでなく、 様々な説明書きを記載するが混乱しがちなので整 理 •  項⽬として"description"や"summary", "title"と いう項⽬名があるが、GFM(GitHub Flavored Markdown)が書けるのは、"description"だけで す。 •  しかし、“description”でもGFMでない (header,securityDefinition)ものもある •  さらに、GFM対応と謳っているのにSwaggerUI では、GFMとして処理されないものやそもそも表 ⽰されない項⽬もある
  34. 34. !tle descrip!on JSON pointer GFM Editor UI アプリケーションのタ イトル 　 #/info/7tle ☓ ◯ ◯ アプリケーションの 説明 アプリケーションの全体 に関する説明は、ここ に記載する。 #/info/descrip7on ◯ ◯ ◯ 拡張ドキュメントのリ ソース Editorは、GFM表示し、 全体がURLのリンク。UI はGFMの解釈はしない #/externalDocs/descrip7on ◯ ◯ △ セキュリティ方式名 Editorは常時画面に表 示、UIは、通常は表示 されず、authoriza7onボ タンを押下した際のポッ プアップモーダル画面 に表示 #/securityDefini7on/{name}/descrip7on ☓ ◯ ◯ OAuth2のスコープ名 同上 #/securityDefini7on/{name}/scopes/{name} ☓ ◯ ◯ リソース操作をグ ルーピング化するタ グの説明 EditorもUIもGFMの解釈 はしない。 #/tags/0/descrip7on ◯ △ △ 拡張ドキュメントのリ ソース EditorもUIも表示されな い #/tags/0/externalDocs/descrip7on ◯ ☓ ☓ 説明⽂の対応状況（全体）
  35. 35. !tle descrip!on JSON pointer　（#/paths/{path}配下） GFM Editor UI リソース操作の概要 　 /{method}/summary ☓ ◯ ◯ リソース操作の説明 　 /{method}/descrip7on ◯ ◯ ◯ リソース操作の拡張ド キュメント説明 UIもEditorも表示さ れない。 /{method}/externalDocs/descrip7on ◯ ☓ ☓ URI単位のパラメータの 説明 EditorもUIもGFMの 解釈はしない。 /parameters/0/descrip7on /{method}/parameters/0/descrip7on ◯ △ △ schemaのタイトル 　 /parameters/0/schema/7tle /{method}/parameters/0/schema/7tle ☓ ◯ ◯ schemaの説明 Editorでは、GFM解 釈はされないが表 示される。UIでは表 示さない。 (JSONEditerでは、 GMF解釈されない が表示される) /parameters/0/schema/descrip7on /{method}/parameters/0/schema/descrip7on ◯ △ ☓ schemaの拡張ドキュメン ト説明 UIもEditorも表示さ れない。 /parameters/0/schema/externalDocs/descrip7on /{method}/parameters/0/schema/externalDocs/descrip7on ◯ ☓ ☓ プロパティ項目のタイト ル 　 /parameters/0/schema/proper7es/{property}/7tle /{method}/parameters/0/schema/proper7es/{property}/7tle ☓ ◯ ◯ プロパティ項目の説明 Editorでは、GFM解 釈はされないが表 示される。UIでは表 示さない。(JSON Editorでは、GMF解 釈されないが表示 される) /parameters/0/schema/proper7es/{property}/descrip7on /{method}/parameters/0/schema/proper7es/{property}/ descrip7on ◯ △ ☓ 説明⽂の対応状況（リクエスト）
  36. 36. !tle descrip!on JSON pointer　（#/paths/{path}配下） GFM Editor UI ステータスコード単位の レスポンスの説明 　 /{method}/responses/{StatusCode}/descrip7on ◯ ◯ ◯ ヘダーの説明 Header objectの descrip7onは、GFM ではない。UI,Editer 共にGFM解釈もし ない。 /{method}/responses/{StatusCode}/headers/{headerName}/ descrip7on ☓ ◯ ◯ スキーマタイトル 　 /{method}/responses/{StatusCode}/schema/7tle ☓ ◯ ◯ スキーマの説明 Editorでは、GFM解 釈はされないが表 示される。UIでは表 示さない。 /{method}/responses/{StatusCode}/schema/descrip7on ◯ △ ☓ schemaの拡張ドキュメン ト説明 UIもEditorも表示さ れない。 /{method}/responses/{StatusCode}/schema/externalDocs/ descrip7on ◯ ☓ ☓ プロパティ項目のタイト ル 　 /{method}/responses/{StatusCode}/schema/proper7es/ {property}/7tle ☓ ◯ ◯ プロパティ項目説明 Editorでは、GFM解 釈はされないが表 示される。UIでは GFM表示される。 /{method}/responses/{StatusCode}/schema/proper7es/ {property}/descrip7on ◯ △ ◯ 説明⽂の対応状況（レスポンス）

×