# ファイルフォーマット規約
# フォーマット
OpenAPI ドキュメントは JSON 形式、YAML 形式いずれかのフォーマットで記載できるが YAML 形式 を利用する。
理由として、JSON と比較して YAML は視覚的に見やすく、レビューや差分管理が行いやすいためである。
# ファイル名
ファイルの拡張子は yaml
とする。通常ファイル名は api.yaml
や swagger.yaml
(v2 の場合) を推奨する。
もし、複数の Swagger 定義を管理するため区別したい場合は ${service}_api.yaml
とする。
${service}
にはサービス名を指定する
# YAML バージョン
YAML v1.2 (opens new window)を用いる。
# ファイルレイアウト
- ファイルの最終行には空行を入れる
- 文字コードは UTF-8 とする
- タブは半角スペース 2 つとする
# クォート
クォートは可読性を上げるために、できる限り利用しない。利用する場合はダブルクォートを利用する。
# OK
description: 何かしらの説明
# NG(クォートでのラップは不要)
description: '何かしらの説明'
description: "何かしらの説明"
1
2
3
4
5
6
2
3
4
5
6
以下の場合は必須で利用する
- 文字列として認識させる必要のある数字("0123")
- 60 進数と認識させたくない場合("12:34")
- Bool として認識させたくない("true", "false", "yes", "no", "y", "n", "on", "off")
#
で始まる文字列(#
はコメントを示す記号のためである。例:#/definitions/Users
)
# YAML 配列スタイル
複数項目を指定する場合は、 Flow style(配列スキーム) を用いることを推奨する
# OK(推奨: 配列リテラル構文) required: [user_id, user_name, account_type, register_at] # NG(非推奨: リスト構文) required: - user_id - user_name - account_type - register_at
1
2
3
4
5
6
7
8
9- YAML は項目定義がネストすることで縦長な定義になりやすい。情報密度を上げるために配列リテラルを推奨する
# 改行の表現
改行を含む場合は、パイプ(ブロックスカラー) |
を用いる
description: |
説明文1
説明文2
- 箇条書き1
- 箇条書き2
- 箇条書き3
1
2
3
4
5
6
2
3
4
5
6