Swaggerでのapi開発よもやま話

Swaggerによる
モデルファースト!?
API開発
よもやま話
by TIS株式会社⼩⻄啓介

⾃⼰紹介
⼩⻄啓介 (KONISHI Keisuke)
•  SIerに勤める12年⽬の現場エンジニア
•  昔
–  XML DBの普及を夢⾒てた
–  XML DB プログラミングコンテストで最優秀賞
•  最近
–  Startup Weekend FinTechで参加チームが、優勝
•  API Meetupの運営チームに参加

Swaggerとの出会い
•  昨年、スマホアプリ向けのAPI開発で
API仕様をExcelで書きたくなかった
– 漏れのないフォーマットが作れない
– 仕様書からAPIスタブを⽣成したい
•  「Swagger」を発⾒
– 佐々⽊拓郎さんのSlide
–  http://www.slideshare.net/takurosasaki/swaggerapi

パイロットプロジェクトの概要

お断り
現在進⾏中の案件の為、業務的な
話や実際に作成したAPI仕様などは、
ご紹介できません。
その代わり? サンプルとして「Redmine
API」のSwagger定義を作成しました。
→ 完成したらGitHubに上げます。(たぶん)

•  期間は３か⽉
•  ⽬的
–  「使われるAPI」を⽬指す
–  API利⽤者に事前公開しフィードバックを得る
•  やること
–  ドラフトAPI仕様の策定
–  サンドボックスの構築
•  進め⽅
–  モデルファースト、Swaggerを全⾯採⽤
–  外部インターフェイスに注⼒
•  既存バックエンドのことはあまり考えない

•  サンドボックスの技術要素
– サーバ(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仕様公開)

フェーズ１：API⾻格検討
•  最初はExcel等で整理(いきなりSwaggerは難しい)
– 業務機能洗い出し
– リソース抽出
– 項⽬名の名寄せ、英字検討
•  Swaggerは項⽬名だけ書く(詳細まで書かない)
– Path
– Operation
– 必須リクエストパラメータ
– 正常系のレスポンス

フェーズ２：サンドボックス構築
•  ⾻格が固まったら詳細記述
– 型(type, format ,pattern(正規表現))
– 必須、最⼩値、最⼤値,ENUM
– description等の説明の充実
– セキュリティ(OAuth関連)
– 共通化定義
– エラー定義

プロジェクトで気が付いたこと
(swagger関連のみ)

Swagger Editorについて(1/2)
•  とても使いやすい、わけではない
– ⼊⼒補助はあるが、賢くはない
– 構⽂エラーを取るのは⼀苦労
•  慣れないと指摘内容がわかりにくい
– 左右の画⾯移動が⼀⽅向のみ (左→右:NG)
•  気が付きにくい機能
– 「Ctrl + F」を２回で置換出来る
– Edit画⾯で階層で折りたためる
•  Swagger UIとの互換性は考えてない！？

Swagger Editorについて(2/2)

Swagger UIについて(1/2)
•  カスタマイズが必要
–  認証関係、バグパッチ対応、⽇本語化
–  修正は、基本index.html、jQueryでOK
•  表⽰されるレスポンスは、加⼯されている
–  CORSのXHRでのエラーは不明
–  304(Not Modiﬁed)は、200で表⽰
•  Chromeの開発画⾯を⾒たほうがいい
•  表⽰されないswaggerの情報がある
–  swaggerファイルも公開すべし
•  ベンダー拡張、内部APIはフィルタ
•  アルファベット順で必ずソートされる
–  apisSorter, operationsSorterは、1.2⽤記述?

Swagger Nodeについて
•  Swagger定義でフォーマットValidation、
単項⽬Validationしてくれるのはとても便利
•  リクエストだけでなく、レスポンスも
Validation可能、ただ、正常系もエラー系も
すべてValidationするのはすこし⼤変
–  additionalProperties:falseにするともっと⼤変
•  もちろん、リクエストのValidationエラーの
レスポンスがレスポンスvalidationエラーに
なることも

Swagger 仕様について(1/6)
•  全体の構成が分かりにくい
– リクエストとレスポンスが⾮対称
•  リクエストは、URIで送る情報、headerで送る情
報、bodyで送る情報をparametersに配列で定義
•  レスポンスは、ステータスコード、headerで受け
取る情報、bodyで受け取る情報をマップで定義
– 仕様書は、オブジェクトの参照関係のみ
•  Object構成図が欲しい！

オブジェクト
構成図
•  仕様書のObjectの
参照関係を階層
構造で定義
•  $refの参照関係を
定義

•  見えないし、分か
らないですよね。。

OpenAPI Speciﬁcation Visual
Documentation
h,p://openapi-
speciﬁca7on-visual-
documenta7on.apihandy
man.io/
※誤記もあるので注意

•  ⼤事な部分は、JSON Schema参照
– リクエストとレスポンスの項⽬定義について、
SwaggerとJSON Schemaのリファレンスを
両⽅みないとよくわからない。
•  オブジェクトの配列に注意
– 配列の識別⼦(“-”)とオブジェクトを別⾏に！
– 基本的にtagsとparameters、security、
allOf４つだけなので覚える！！

•  “host”パラメータは、任意
– 書かなければ、ドキュメントのホスト
•  環境毎に書き換えなくていいので便利
– ただし、セキュリティ定義の(authorization
uri/token uri)は絶対URLで”host”とは無関係
•  PJでは、SwaggerUIをカスタマイズして、
descriptionを含めて、全てのURLをjQueryで⾃動
的に書き換えました

•  レスポンスのエラー定義
– レスポンスの定義は、ステータスコード単位
– “400”で業務エラーを定義すると、業務エ
ラーコード等の定義が集中してしまう
– 業務エラーコードの情報をどこに書くか注意
•  Swaggerの外部に書くのもあり
–  ただし、externalDocsは、UIでは、表⽰されないので、
descriptionにリンクを書く

気が付いたこと（まとめ）
•  Swagger 仕様は結構難しい
•  Swagger EditorとUIで違う
•  Swagger UIは、カスタマイズが必要
•  内部⽤と外部⽤でSwaggerを分けたくなる
けど極⼒分けない(⽣成する)

Swagger仕様でよく悩むこと

定義の共通化について
•  Swaggerを書いていると、リクエストやレ
スポンス等に同⼀定義が繰り返し出てくる
•  これらを共通化するのが、Referenceオブ
ジェクト($ref)による参照である。
•  Swaggerの仕様では、Referenceオブジェク
トをさまざまな場所に記載できるが、少しわ
かりにくいので整理する。
•  外部ファイル参照については、取り上げない。

定義の共通化について
•  参照先の定義は３種類
–  Parameters Definitions
•  Parameterオブジェクトを定義
–  Responses Definitions
•  Responseオブジェクトを定義
–  (Schema) Definitions
•  Schemaオブジェクトを定義
•  Parameters,Responsesは⾃⾝参照出来ない
•  DefinitionsはDefinitionsは⾃⼰参照することが出来る
•  ただし、Alias的(直接$refする)な参照は⾮推奨?警告
が出る
•  responseのheaderの共⽤化は、出来ない

Parameters Deﬁnitions
•  参照元JSON Pointer
–  #/paths/{path}/parameters/0/$ref
–  #/paths/{path}/{method}/parameters/0/$ref
•  参照先JSON Pointer
– #/parameters/{name}

Parameters Deﬁnitions
#/ parameters /{name}
#/paths/{path}/parameters/0/$ref
#/paths/{path}/{method}/parameters/0/$ref

Responses Deﬁnitions
•  参照元(JSON Pointer)
–  #/paths/{path}/{method}/responses/{StatusCode}/$ref
•  参照先(JSON Pointer)
– #/responses/{name}

Responses Deﬁnitions
#/ responses /{name}
#/paths/{path}/{method}/responses/{StatusCode}/$ref

(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}

(schema) Deﬁnitions
#/paths/{path}/{method}/parameters/0/schema
#/deﬁni7ons/{name}

description等の説明⽂の記載
•  Swaggerは、API仕様ですので、定義だけでなく、
様々な説明書きを記載するが混乱しがちなので整
理
•  項⽬として"description"や"summary", "title"と
いう項⽬名があるが、GFM(GitHub Flavored
Markdown)が書けるのは、"description"だけで
す。
•  しかし、“description”でもGFMでない
(header,securityDeﬁnition)ものもある
•  さらに、GFM対応と謳っているのにSwaggerUI
では、GFMとして処理されないものやそもそも表
⽰されない項⽬もある

!tle descrip!on JSON pointer GFM Editor UI
アプリケーションのタ
イトル
　 #/info/7tle ☓ ◯ ◯
アプリケーションの
説明
アプリケーションの全体
に関する説明は、ここ
に記載する。
#/info/descrip7on ◯ ◯ ◯
拡張ドキュメントのリ
ソース
Editorは、GFM表示し、
全体がURLのリンク。UI
はGFMの解釈はしない
#/externalDocs/descrip7on ◯ ◯ △
セキュリティ方式名
Editorは常時画面に表
示、UIは、通常は表示
されず、authoriza7onボ
タンを押下した際のポッ
プアップモーダル画面
に表示
#/securityDeﬁni7on/{name}/descrip7on ☓ ◯ ◯
OAuth2のスコープ名同上 #/securityDeﬁni7on/{name}/scopes/{name} ☓ ◯ ◯
リソース操作をグ
ルーピング化するタ
グの説明
EditorもUIもGFMの解釈
はしない。
#/tags/0/descrip7on ◯ △ △
拡張ドキュメントのリ
ソース
EditorもUIも表示されな
い
#/tags/0/externalDocs/descrip7on ◯ ☓ ☓
説明⽂の対応状況（全体）

!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の拡張ドキュメン
ト説明
れない。
/parameters/0/schema/externalDocs/descrip7on
/{method}/parameters/0/schema/externalDocs/descrip7on
◯ ☓ ☓
プロパティ項目のタイト
ル
　
/parameters/0/schema/proper7es/{property}/7tle
/{method}/parameters/0/schema/proper7es/{property}/7tle
☓ ◯ ◯
プロパティ項目の説明
示さない。(JSON
Editorでは、GMF解
釈されないが表示
される)
/parameters/0/schema/proper7es/{property}/descrip7on
/{method}/parameters/0/schema/proper7es/{property}/
descrip7on
◯ △ ☓
説明⽂の対応状況（リクエスト）

!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 ☓ ◯ ◯
スキーマの説明
示さない。
/{method}/responses/{StatusCode}/schema/descrip7on ◯ △ ☓
schemaの拡張ドキュメン
ト説明
れない。
/{method}/responses/{StatusCode}/schema/externalDocs/
descrip7on
◯ ☓ ☓
プロパティ項目のタイト
ル
　
/{method}/responses/{StatusCode}/schema/proper7es/
{property}/7tle
☓ ◯ ◯
プロパティ項目説明
示される。UIでは
GFM表示される。
/{method}/responses/{StatusCode}/schema/proper7es/
{property}/descrip7on
◯ △ ◯
説明⽂の対応状況（レスポンス）

Swaggerでのapi開発よもやま話

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Viewers also liked

Viewers also liked (20)

Similar to Swaggerでのapi開発よもやま話

Similar to Swaggerでのapi開発よもやま話 (20)

Swaggerでのapi開発よもやま話

Editor's Notes