2020/09/25の勉強会で発表されたものです。

1. 2020/09/25
Open APIで定義しよう！ 実践編
REST APIをどう文書化するか迷った時の処方箋。当資料はOpen API 3.0を前提にしています

2. 前回のあらすじ
✤ Open API を使ってREST APIの定義をする話をした

3. スキーマ(schema)定義について
✤ typeは、string・number・integer・boolean・
array・objectのいずれかを選択する
✤ stirngの中には、日付型・ファイル型も含まれ
るものとする。詳しくは後述
✤ 「string型もしくはinteger型」などといった混
合型を示したい場合は後述

4. スキーマ(schema)定義について
✤ 上から順に、普通の文字列・日付文字列・時刻文字列・Base64
型でエンコードされたバイナリ型・素のバイナリ型
✤ 日付文字列は例えば「2017-07-21」、時刻文字列は例えば「
2017-07-21T17:32:28Z」
✤ どちらもRFC 3339, section 5.6に準拠している
✤ オリジナルなformatを定義してもいい(解釈はツール側に任せる)

5. スキーマ(schema)定義について
✤ type: arrayだと配列型、type: objectだと
辞書型になる
✤ 配列型だとitems:以下に任意の
schemaを指定できる(＝入れ子にでき
る)
✤ 辞書型だとproperties:→キー名:以下に
任意のschemaを指定できる(＝入れ子
にできる)
辞書型のプロパティの
中で必須なものを指定

6. スキーマ(schema)定義について
✤ oneOfを使うことで、「いくつかあるうち
どれかの型(混合型)」を表現できる
✤ type: nullは存在しない。代わりに、型を
nullable: trueとして修飾する
✤ descriptionで型についての説明、example
で入力例、defaultでデフォルト値を記述で
きる

7. リクエストボディ
✤ MIMEタイプ毎に記述できる
✤ 別に必須ではないので、必須な場合
は「required: true」を忘れずに

8. リクエストヘッダー
✤ リクエストボディはrequestBodyだが、
リクエストヘッダーはrequestHeaderで
はなく別の記法になる
✤ Content-Type・Accept・Authorization
は別の記法を使用するので、ここには
記述しない

9. リクエストパラメーター
✤ もちろん、URL内に含むパラメーター(GET
パラメーター含む)も記述可能
✤ 複数個要求する場合は複数回「in:」を書く
✤ 記法から察せられるように、リクエストヘ
ッダーもリクエストパラメーターの一部扱
いである

10. レスポンス
✤ HTTPステータスコード別に記述する
✤ schema定義についてはリクエストボ
ディのそれと同様の書式

11. スキーマ定義やヘッダー定義などを使い回す場合
✤ components:内に定義すれば使い回せる
✤ 使い回す際は、「$ref:
‘#/components/schemas/User’」といった
風に記述する
✤ 定義できるヘッダー定義は、リクエスト
ヘッダーではなくレスポンスヘッダーな
ことに注意

12. 参考資料
✤ 公式ドキュメント
✤ https://swagger.io/docs/specification/about/
✤ OpenAPI (Swagger) 超入門
✤ https://qiita.com/teinen_qiita/items/e440ca7b1b52ec918f1b