Future Enterprise Coding Standards

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

# フォーマット

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

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

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