# ファイルフォーマット規約

# フォーマット

OpenAPI ドキュメントは JSON 形式、YAML 形式いずれかのフォーマットで記載できるが YAML 形式 を利用する。

理由として、JSON と比較して YAML は視覚的に見やすく、レビューや差分管理が行いやすいためである。

# ファイル名

ファイルの拡張子は yaml とする。通常ファイル名は api.yamlswagger.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

以下の場合は必須で利用する

  • 文字列として認識させる必要のある数字("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