More Related Content
Similar to Swaggerでのapi開発よもやま話 (20)
Swaggerでのapi開発よもやま話
- 2. ⾃⼰紹介
⼩⻄ 啓介 (KONISHI Keisuke)
• SIerに勤める12年⽬の現場エンジニア
• 昔
– XML DBの普及を夢⾒てた
– XML DB プログラミングコンテストで最優秀賞
• 最近
– Startup Weekend FinTechで参加チームが、優勝
• API Meetupの運営チームに参加
- 7. パイロットプロジェクトの概要
• 期間は3か⽉
• ⽬的
– 「使われるAPI」を⽬指す
– API利⽤者に事前公開しフィードバックを得る
• やること
– ドラフトAPI仕様の策定
– サンドボックスの構築
• 進め⽅
– モデルファースト、Swaggerを全⾯採⽤
– 外部インターフェイスに注⼒
• 既存バックエンドのことはあまり考えない
- 14. Swagger UIについて(1/2)
• カスタマイズが必要
– 認証関係、バグパッチ対応、⽇本語化
– 修正は、基本index.html、jQueryでOK
• 表⽰されるレスポンスは、加⼯されている
– CORSのXHRでのエラーは不明
– 304(Not Modified)は、200で表⽰
• Chromeの開発画⾯を⾒たほうがいい
• 表⽰されないswaggerの情報がある
– swaggerファイルも公開すべし
• ベンダー拡張、内部APIはフィルタ
• アルファベット順で必ずソートされる
– apisSorter, operationsSorterは、1.2⽤記述?
- 20. Swagger 仕様について(4/6)
• ⼤事な部分は、JSON Schema参照
– リクエストとレスポンスの項⽬定義について、
SwaggerとJSON Schemaのリファレンスを
両⽅みないとよくわからない。
• オブジェクトの配列に注意
– 配列の識別⼦(“-”)とオブジェクトを別⾏に!
– 基本的にtagsとparameters、security、
allOf4つだけなので覚える!!
- 26. 定義の共通化について
• 参照先の定義は3種類
– Parameters Definitions
• Parameterオブジェクトを定義
– Responses Definitions
• Responseオブジェクトを定義
– (Schema) Definitions
• Schemaオブジェクトを定義
• Parameters,Responsesは⾃⾝参照出来ない
• DefinitionsはDefinitionsは⾃⼰参照することが出来る
• ただし、Alias的(直接$refする)な参照は⾮推奨?警告
が出る
• responseのheaderの共⽤化は、出来ない
- 27. Parameters Definitions
• 参照元JSON Pointer
– #/paths/{path}/parameters/0/$ref
– #/paths/{path}/{method}/parameters/0/$ref
• 参照先JSON Pointer
– #/parameters/{name}
- 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)
– {参照元1}/$ref
– {参照元1}/items/$ref
– {参照元1}/properties/{property}/$ref
– {参照元1}/properties/{property}/additionalProperties/$ref
– {参照元1}/properties/{property}/allOf/0/$ref
• 参照先(JSON Pointer)
– #/definitions/{name}
- 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. !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. !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
◯ △ ◯
説明⽂の対応状況(レスポンス)
Editor's Notes
- 入社12年目のいわゆるSEです。金融系のお客様のシステム構築や保守を主に行ってきました。
技術的には、XMLが好きで、業務システムにXML DBが採用されることを夢見てました。
もう8年も前ですがXML DBプログラミングコンテストというニッチなコンテストで最優秀賞をもらいました。
最近では、Startup Weekend Fintechで、ソーシャルレンディングのチームに参加してMVPを作成し優勝しました。
- ※ここでお断りしてさせて頂きますが、今回のご紹介する取り組みは、現在進行中の話もあり具体的な案件の内容やAPIの仕様についてお見せできないことをご了承ください。
その代わりと言ってなんですが、Redmine のAPIをSwaggerに起こしてみましたのでSwaggerファイルのサンプルをご覧頂く際には、そちらをお見せします。→ たぶんGitHubに上げます。
- その後、サンドボックスの構築を開始しましたが、ここでは、バックエンドの業務処理実装とSwaggerの詳細記述を並行して行いました。Swaggerの精緻記述とは、各パラメータの型や桁数、正規表現による文字列形式最大値、最小値の定義、ENUMの定義やOAuthのセキュリティ記述やエラーのステータス定義やエラーのレスポンス定義、業務エラーコードの記載などを行って行きました。「モデルファースト」でない感じもしますが、サンドボックスの実装に依存する記載もありますし、最初からすべてのSwagger定義を記載するのは難しと感じています。なお、status:400で同一の構造である必要がある為、Swagger-toolsのエラーレスポンスは再編集するようにしました。
- SwaggerUIは、カスタマイズがだいたい必要、基本はindex.htmlを治すだけ。jQueryを使ったことがあれば十分出来る。
認証関係のカスタマイズは、結構面倒
swaggerUIにbasic認証をかけるて、OAuth認証すると再読み込みで使えない。
tagsを複数定義すると、tagごとに整理されて重複表示される。
SwaggerUIは日本語化が出来る。翻訳対象項目には、辞書があるので、対訳を修正することで表示文言を変えられる。
制約値(minimam valueなど)が表示されない、これは結構辛かった。ポップアップで表示されるようになったが、
どの項目のポップアップかかわならいので、項目名を表示されるように修正した。
API利用者には、UIだけでなく、swaggerファイルを提供したほうが、コピペなどをする際に便利かもしれない。
ただし、共通化を進めているとswaggerファイルを見ても最終的な構造はわかりにくいかも
swaggerファイル自体も公開すべき
- SwaggerUIは、カスタマイズがだいたい必要、基本はindex.htmlを治すだけ。jQueryを使ったことがあれば十分出来る。
認証関係のカスタマイズは、結構面倒
swaggerUIにbasic認証をかけるて、OAuth認証すると再読み込みで使えない。
tagsを複数定義すると、tagごとに整理されて重複表示される。
SwaggerUIは日本語化が出来る。翻訳対象項目には、辞書があるので、対訳を修正することで表示文言を変えられる。
制約値(minimam valueなど)が表示されない、これは結構辛かった。ポップアップで表示されるようになったが、
どの項目のポップアップかかわならいので、項目名を表示されるように修正した。
API利用者には、UIだけでなく、swaggerファイルを提供したほうが、コピペなどをする際に便利かもしれない。
ただし、共通化を進めているとswaggerファイルを見ても最終的な構造はわかりにくいかも
swaggerファイル自体も公開すべき
- YAMLはネスト構造で見やすいが、オブジェクトの配列は、非常に見づらく、
オブジェクトの配列は、見づらい、配列の - を空行として、次の行に書くべき
hostパラメータは、書かなければ、ドキュメントのカレントhostを示すので
単体環境、試験環境、本番環境で切り替えを行う場合はあえて書かないほうが良いかもしれません。
ただし、authorization uri/token uriは、hostパラメータに依存しないので、
何らか対策が必要ですね。私は、swagger UIのクライアント上で切り替えていました。
1ソースマルチユースを実現するのは、結構たいへんです。
だいたい、内部用と外部用に分けたくなります。
これは、x-のベンダープリフィックスもそうですし、バックエンド上で内部用のAPIと外部用のAPIの
両方の実装を行い、API-GWなどでセキュリティ設定を行った場合、
swagger上に公開したいものと、したくないものが混在するケースがあると思います。
キーベースでのfilter機能を使って同一機能を利用しました。
大量の業務エラーのコードを書くのは辛い。別に一覧を書くべきかもしれない。
- また、YAMLで記載している場合特に オブジェクトと配列がわかりにくくなる。オブジェクトの配列については、配列の識別子("-")と先頭のオブジェクトを同一行に書かずに識別子だけを一行目に書き、二行目以降にオブジェクトを並べるのもありかもしれない。parameters: - in: query name: offset type: integer - in: query name: limit type: integerparameters: - in: query name: offset type: integer - in: query name: limit type: integerまた、swaggerで配列のオブジェクトになるのは、tagsとparametersとsecurityだけなので、覚えてしまうのもありかもしれない。
- YAMLはネスト構造で見やすいが、オブジェクトの配列は、非常に見づらく、
オブジェクトの配列は、見づらい、配列の - を空行として、次の行に書くべき
hostパラメータは、書かなければ、ドキュメントのカレントhostを示すので
単体環境、試験環境、本番環境で切り替えを行う場合はあえて書かないほうが良いかもしれません。
ただし、authorization uri/token uriは、hostパラメータに依存しないので、
何らか対策が必要ですね。私は、swagger UIのクライアント上で切り替えていました。
1ソースマルチユースを実現するのは、結構たいへんです。
だいたい、内部用と外部用に分けたくなります。
これは、x-のベンダープリフィックスもそうですし、バックエンド上で内部用のAPIと外部用のAPIの
両方の実装を行い、API-GWなどでセキュリティ設定を行った場合、
swagger上に公開したいものと、したくないものが混在するケースがあると思います。
キーベースでのfilter機能を使って同一機能を利用しました。
大量の業務エラーのコードを書くのは辛い。別に一覧を書くべきかもしれない。
- YAMLはネスト構造で見やすいが、オブジェクトの配列は、非常に見づらく、
オブジェクトの配列は、見づらい、配列の - を空行として、次の行に書くべき
hostパラメータは、書かなければ、ドキュメントのカレントhostを示すので
単体環境、試験環境、本番環境で切り替えを行う場合はあえて書かないほうが良いかもしれません。
ただし、authorization uri/token uriは、hostパラメータに依存しないので、
何らか対策が必要ですね。私は、swagger UIのクライアント上で切り替えていました。
1ソースマルチユースを実現するのは、結構たいへんです。
だいたい、内部用と外部用に分けたくなります。
これは、x-のベンダープリフィックスもそうですし、バックエンド上で内部用のAPIと外部用のAPIの
両方の実装を行い、API-GWなどでセキュリティ設定を行った場合、
swagger上に公開したいものと、したくないものが混在するケースがあると思います。
キーベースでのfilter機能を使って同一機能を利用しました。
大量の業務エラーのコードを書くのは辛い。別に一覧を書くべきかもしれない。
- Swaggerを書いていると、リクエストやレスポンス等に同一定義が繰り返し出てくる。
これらを共通化するのが、Referenceオブジェクト($ref)による参照である。
Swaggerの仕様では、Referenceオブジェクトを継承して新たなReferenceオブジェクトを
定義することが出来るなど、さまざまな機能があるが、少しわかりにくいので
整理する。
・参照先は3種類、Parameters,Responses,Definitions
・Parameters,Responsesは自身を参照することは出来ない。Definitionsへの参照は可能。
・DefinitionsはDefinitionsを参照することが出来る。ただし、Alias的(直接$refする)な参照は警告が出る。
・responseのheaderの参照共用化は、出来ない。
■Parameters Definitionsオブジェクト参照
#/paths/{path}/parameters/0/$ref
#/paths/{path}/{method}/parameters/0/$ref
→ #/parameters/{name} (Parameterオブジェクトを定義)
■Responses Definitionsオブジェクト参照
#/paths/{path}/{method}/responses/{StatusCode}/$ref
→ #/responses/{name} (Responseオブジェクトを定義)
■Definitionsオブジェクト参照
#/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}
/$ref
/items/$ref
/properties/{property}/$ref
/properties/{property}/additionalProperties/$ref
/properties/{property}/allOf/0/$ref
→ #/definitions/{name} Schemaオブジェクトを定義
※{method}=get|put|post|delete|options|head|patch
■外部ファイル(YAML,JSON)参照
#/paths/{path}/$ref: '{path}.yaml' ※外部YAML,JSON参照
- Swaggerを書いていると、リクエストやレスポンス等に同一定義が繰り返し出てくる。
これらを共通化するのが、Referenceオブジェクト($ref)による参照である。
Swaggerの仕様では、Referenceオブジェクトを継承して新たなReferenceオブジェクトを
定義することが出来るなど、さまざまな機能があるが、少しわかりにくいので
整理する。
・参照先は3種類、Parameters,Responses,Definitions
・Parameters,Responsesは自身を参照することは出来ない。Definitionsへの参照は可能。
・DefinitionsはDefinitionsを参照することが出来る。ただし、Alias的(直接$refする)な参照は警告が出る。
・responseのheaderの参照共用化は、出来ない。
■Parameters Definitionsオブジェクト参照
#/paths/{path}/parameters/0/$ref
#/paths/{path}/{method}/parameters/0/$ref
→ #/parameters/{name} (Parameterオブジェクトを定義)
■Responses Definitionsオブジェクト参照
#/paths/{path}/{method}/responses/{StatusCode}/$ref
→ #/responses/{name} (Responseオブジェクトを定義)
■Definitionsオブジェクト参照
#/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}
/$ref
/items/$ref
/properties/{property}/$ref
/properties/{property}/additionalProperties/$ref
/properties/{property}/allOf/0/$ref
→ #/definitions/{name} Schemaオブジェクトを定義
※{method}=get|put|post|delete|options|head|patch
■外部ファイル(YAML,JSON)参照
#/paths/{path}/$ref: '{path}.yaml' ※外部YAML,JSON参照
- Swaggerを書いていると、リクエストやレスポンス等に同一定義が繰り返し出てくる。
これらを共通化するのが、Referenceオブジェクト($ref)による参照である。
Swaggerの仕様では、Referenceオブジェクトを継承して新たなReferenceオブジェクトを
定義することが出来るなど、さまざまな機能があるが、少しわかりにくいので
整理する。
・参照先は3種類、Parameters,Responses,Definitions
・Parameters,Responsesは自身を参照することは出来ない。Definitionsへの参照は可能。
・DefinitionsはDefinitionsを参照することが出来る。ただし、Alias的(直接$refする)な参照は警告が出る。
・responseのheaderの参照共用化は、出来ない。
■Parameters Definitionsオブジェクト参照
#/paths/{path}/parameters/0/$ref
#/paths/{path}/{method}/parameters/0/$ref
→ #/parameters/{name} (Parameterオブジェクトを定義)
■Responses Definitionsオブジェクト参照
#/paths/{path}/{method}/responses/{StatusCode}/$ref
→ #/responses/{name} (Responseオブジェクトを定義)
■Definitionsオブジェクト参照
#/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}
/$ref
/items/$ref
/properties/{property}/$ref
/properties/{property}/additionalProperties/$ref
/properties/{property}/allOf/0/$ref
→ #/definitions/{name} Schemaオブジェクトを定義
※{method}=get|put|post|delete|options|head|patch
■外部ファイル(YAML,JSON)参照
#/paths/{path}/$ref: '{path}.yaml' ※外部YAML,JSON参照
- Swaggerを書いていると、リクエストやレスポンス等に同一定義が繰り返し出てくる。
これらを共通化するのが、Referenceオブジェクト($ref)による参照である。
Swaggerの仕様では、Referenceオブジェクトを継承して新たなReferenceオブジェクトを
定義することが出来るなど、さまざまな機能があるが、少しわかりにくいので
整理する。
・参照先は3種類、Parameters,Responses,Definitions
・Parameters,Responsesは自身を参照することは出来ない。Definitionsへの参照は可能。
・DefinitionsはDefinitionsを参照することが出来る。ただし、Alias的(直接$refする)な参照は警告が出る。
・responseのheaderの参照共用化は、出来ない。
■Parameters Definitionsオブジェクト参照
#/paths/{path}/parameters/0/$ref
#/paths/{path}/{method}/parameters/0/$ref
→ #/parameters/{name} (Parameterオブジェクトを定義)
■Responses Definitionsオブジェクト参照
#/paths/{path}/{method}/responses/{StatusCode}/$ref
→ #/responses/{name} (Responseオブジェクトを定義)
■Definitionsオブジェクト参照
#/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}
/$ref
/items/$ref
/properties/{property}/$ref
/properties/{property}/additionalProperties/$ref
/properties/{property}/allOf/0/$ref
→ #/definitions/{name} Schemaオブジェクトを定義
※{method}=get|put|post|delete|options|head|patch
■外部ファイル(YAML,JSON)参照
#/paths/{path}/$ref: '{path}.yaml' ※外部YAML,JSON参照
- Swaggerを書いていると、リクエストやレスポンス等に同一定義が繰り返し出てくる。
これらを共通化するのが、Referenceオブジェクト($ref)による参照である。
Swaggerの仕様では、Referenceオブジェクトを継承して新たなReferenceオブジェクトを
定義することが出来るなど、さまざまな機能があるが、少しわかりにくいので
整理する。
・参照先は3種類、Parameters,Responses,Definitions
・Parameters,Responsesは自身を参照することは出来ない。Definitionsへの参照は可能。
・DefinitionsはDefinitionsを参照することが出来る。ただし、Alias的(直接$refする)な参照は警告が出る。
・responseのheaderの参照共用化は、出来ない。
■Parameters Definitionsオブジェクト参照
#/paths/{path}/parameters/0/$ref
#/paths/{path}/{method}/parameters/0/$ref
→ #/parameters/{name} (Parameterオブジェクトを定義)
■Responses Definitionsオブジェクト参照
#/paths/{path}/{method}/responses/{StatusCode}/$ref
→ #/responses/{name} (Responseオブジェクトを定義)
■Definitionsオブジェクト参照
#/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}
/$ref
/items/$ref
/properties/{property}/$ref
/properties/{property}/additionalProperties/$ref
/properties/{property}/allOf/0/$ref
→ #/definitions/{name} Schemaオブジェクトを定義
※{method}=get|put|post|delete|options|head|patch
■外部ファイル(YAML,JSON)参照
#/paths/{path}/$ref: '{path}.yaml' ※外部YAML,JSON参照
- Swaggerを書いていると、リクエストやレスポンス等に同一定義が繰り返し出てくる。
これらを共通化するのが、Referenceオブジェクト($ref)による参照である。
Swaggerの仕様では、Referenceオブジェクトを継承して新たなReferenceオブジェクトを
定義することが出来るなど、さまざまな機能があるが、少しわかりにくいので
整理する。
・参照先は3種類、Parameters,Responses,Definitions
・Parameters,Responsesは自身を参照することは出来ない。Definitionsへの参照は可能。
・DefinitionsはDefinitionsを参照することが出来る。ただし、Alias的(直接$refする)な参照は警告が出る。
・responseのheaderの参照共用化は、出来ない。
■Parameters Definitionsオブジェクト参照
#/paths/{path}/parameters/0/$ref
#/paths/{path}/{method}/parameters/0/$ref
→ #/parameters/{name} (Parameterオブジェクトを定義)
■Responses Definitionsオブジェクト参照
#/paths/{path}/{method}/responses/{StatusCode}/$ref
→ #/responses/{name} (Responseオブジェクトを定義)
■Definitionsオブジェクト参照
#/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}
/$ref
/items/$ref
/properties/{property}/$ref
/properties/{property}/additionalProperties/$ref
/properties/{property}/allOf/0/$ref
→ #/definitions/{name} Schemaオブジェクトを定義
※{method}=get|put|post|delete|options|head|patch
■外部ファイル(YAML,JSON)参照
#/paths/{path}/$ref: '{path}.yaml' ※外部YAML,JSON参照
- Swaggerを書いていると、リクエストやレスポンス等に同一定義が繰り返し出てくる。
これらを共通化するのが、Referenceオブジェクト($ref)による参照である。
Swaggerの仕様では、Referenceオブジェクトを継承して新たなReferenceオブジェクトを
定義することが出来るなど、さまざまな機能があるが、少しわかりにくいので
整理する。
・参照先は3種類、Parameters,Responses,Definitions
・Parameters,Responsesは自身を参照することは出来ない。Definitionsへの参照は可能。
・DefinitionsはDefinitionsを参照することが出来る。ただし、Alias的(直接$refする)な参照は警告が出る。
・responseのheaderの参照共用化は、出来ない。
■Parameters Definitionsオブジェクト参照
#/paths/{path}/parameters/0/$ref
#/paths/{path}/{method}/parameters/0/$ref
→ #/parameters/{name} (Parameterオブジェクトを定義)
■Responses Definitionsオブジェクト参照
#/paths/{path}/{method}/responses/{StatusCode}/$ref
→ #/responses/{name} (Responseオブジェクトを定義)
■Definitionsオブジェクト参照
#/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}
/$ref
/items/$ref
/properties/{property}/$ref
/properties/{property}/additionalProperties/$ref
/properties/{property}/allOf/0/$ref
→ #/definitions/{name} Schemaオブジェクトを定義
※{method}=get|put|post|delete|options|head|patch
■外部ファイル(YAML,JSON)参照
#/paths/{path}/$ref: '{path}.yaml' ※外部YAML,JSON参照
- Swaggerを書いていると、リクエストやレスポンス等に同一定義が繰り返し出てくる。
これらを共通化するのが、Referenceオブジェクト($ref)による参照である。
Swaggerの仕様では、Referenceオブジェクトを継承して新たなReferenceオブジェクトを
定義することが出来るなど、さまざまな機能があるが、少しわかりにくいので
整理する。
・参照先は3種類、Parameters,Responses,Definitions
・Parameters,Responsesは自身を参照することは出来ない。Definitionsへの参照は可能。
・DefinitionsはDefinitionsを参照することが出来る。ただし、Alias的(直接$refする)な参照は警告が出る。
・responseのheaderの参照共用化は、出来ない。
■Parameters Definitionsオブジェクト参照
#/paths/{path}/parameters/0/$ref
#/paths/{path}/{method}/parameters/0/$ref
→ #/parameters/{name} (Parameterオブジェクトを定義)
■Responses Definitionsオブジェクト参照
#/paths/{path}/{method}/responses/{StatusCode}/$ref
→ #/responses/{name} (Responseオブジェクトを定義)
■Definitionsオブジェクト参照
#/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}
/$ref
/items/$ref
/properties/{property}/$ref
/properties/{property}/additionalProperties/$ref
/properties/{property}/allOf/0/$ref
→ #/definitions/{name} Schemaオブジェクトを定義
※{method}=get|put|post|delete|options|head|patch
■外部ファイル(YAML,JSON)参照
#/paths/{path}/$ref: '{path}.yaml' ※外部YAML,JSON参照