0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@zooko

OpenAPI仕様書はJSONとYAMLどっちで書くべき？

0
Posted at

はじめに

OpenAPIの仕様書を書くとき、JSONとYAMLの2種類のフォーマットが使えます。「なぜ2種類あるの？」「どっちを選べばいいの？」と迷う方も多いはずです。この記事では、それぞれのメリット・デメリット・使い分けを整理し、同じAPIを両フォーマットで書いた具体例も紹介します。

なぜ2種類あるのか？

OpenAPIの仕様は元々、Swaggerという仕様から発展しました。

経緯 説明
JSON Web APIのデータ交換形式として普及しており、Swaggerの初期から採用されていた
YAML JSONのスーパーセット（上位互換）として設計されており、より人間が読みやすいため後から採用された

YAMLはJSONを包含する設計になっているため、有効なJSONは有効なYAMLでもあります。つまり技術的には同じデータ構造を表現でき、どちらを選んでもツールの互換性は保たれます。OpenAPIが両方に対応しているのは、チームや用途によって使いやすい方を選べるようにするためです。

それぞれのメリット

JSON のメリット

メリット 詳細
言語サポートが豊富 ほぼすべてのプログラミング言語に標準のJSON読み書きライブラリがある
ツール・エコシステムが成熟 バリデーター・エディタ補完・Linterなどのサポートが手厚い
構造が厳格で曖昧さがない 型変換や暗黙のルールがなく、パース結果が予測しやすい
Webとの親和性が高い REST APIのレスポンスがJSON形式なので、仕様書とレスポンスを統一できる
プログラムから扱いやすい JSON.stringify() / JSON.parse() などで簡単にシリアライズ・デシリアライズできる

YAML のメリット

メリット 詳細
コメントが書ける # でコメントを残せるため、設計意図や注意点を仕様書内に記録できる
記述が簡潔 引用符やカンマが不要で、JSONより大幅に行数が減る
人間が読みやすい インデントによる階層表現が直感的で、ネストが深くても把握しやすい
複数行テキストが自然 `
JSONと互換性がある 有効なJSONはYAMLとしても有効なので、既存のJSON資産をそのまま取り込める

それぞれのデメリット

JSON のデメリット

デメリット 詳細
コメントが書けない JSON仕様上、// や /* */ のコメントは非サポート。理由や注意点を仕様書内に残せない
冗長になりやすい 引用符、カンマ、波括弧・角括弧が必須で、記述量が多くなる
人間が読みにくい ネストが深くなると視覚的に把握しにくい
末尾カンマが使えない リストや辞書の最後の要素にカンマをつけるとエラーになり、追記・削除時に凡ミスが起きやすい
複数行文字列が不自然 \n でエスケープするしかなく、説明文が読みづらい

YAML のデメリット

デメリット 詳細
インデントに厳格 スペース数が違うだけでパースエラーになる。タブは使用不可
暗黙の型変換がある yes/no/on/off がbooleanに、1.0 が数値に自動変換されることがある（YAML 1.1の挙動）
複雑な構造が分かりにくい アンカー（&）とエイリアス（*）を使った参照は強力だが、読み解くのが難しい
ツールサポートがやや弱い 一部の古いツールやエディタではJSONほどのバリデーション・補完が効かない場合がある
空白の違いがバグを生む コピペ時にインデントがずれると気づきにくいエラーになる

どちらを使うべきか？推奨ガイド

結論：基本はYAML推奨

OpenAPIの仕様書は「人間が読み書きするドキュメント」という側面が強いため、可読性の高いYAMLが多くのケースで適しています。

使い分けの基準

状況 推奨フォーマット 理由
チームで共同編集する YAML コメントで意図・注意点を残せる
GitHubでレビューする YAML diffが読みやすく、レビューしやすい
APIが複雑で仕様書が長い YAML 記述量が少なく見通しがよい
プログラムから動的に生成する JSON 多くの言語でJSONシリアライズが標準サポート
既存システムがJSONを要求する JSON ツール・パイプラインの互換性を優先
フロントエンドのJSコードと連携する JSON JSON.parse() でそのまま扱える

まとめると

  • 手で書く・チームで管理する → YAML
  • コードで生成・外部ツールに渡す → JSON

具体例：同じAPIを両フォーマットで書く

ユーザー一覧を取得する GET /users というシンプルなエンドポイントを例に、両フォーマットで書き比べます。

YAML版

openapi: "3.0.3"
info:
  title: ユーザー管理API
  version: "1.0.0"
  description: ユーザーの取得・登録ができるAPI

paths:
  /users:
    get:
      summary: ユーザー一覧取得
      description: 登録されているユーザーの一覧を返す
      # ページネーションは今後対応予定
      parameters:
        - name: limit
          in: query
          required: false
          description: 取得件数の上限（デフォルト: 20）
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: 取得成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
        "500":
          description: サーバーエラー

components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
        - email
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: 山田太郎
        email:
          type: string
          format: email
          example: yamada@example.com

JSON版

{
  "openapi": "3.0.3",
  "info": {
    "title": "ユーザー管理API",
    "version": "1.0.0",
    "description": "ユーザーの取得・登録ができるAPI"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "ユーザー一覧取得",
        "description": "登録されているユーザーの一覧を返す",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "取得件数の上限（デフォルト: 20）",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "取得成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/User"
                  }
                }
              }
            }
          },
          "500": {
            "description": "サーバーエラー"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "required": ["id", "name", "email"],
        "properties": {
          "id": {
            "type": "integer",
            "example": 1
          },
          "name": {
            "type": "string",
            "example": "山田太郎"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "yamada@example.com"
          }
        }
      }
    }
  }
}

見比べてわかること

比較ポイント YAML JSON
行数 約40行 約65行
コメント # ページネーションは今後対応予定 と書ける 書けない
引用符 キーに不要（基本） すべてのキーに " が必要
末尾カンマ 不要 最後の要素以外は必須（忘れるとエラー）
ネストの把握 インデントで直感的にわかる { } の対応を追う必要がある

まとめ

  • OpenAPIがJSONとYAMLの両方に対応しているのは、用途・チーム・ツールによって最適解が異なるから
  • 人間が書いて管理するなら YAML：コメントが書ける・記述量が少ない・可読性が高い
  • プログラムで生成・外部連携するなら JSON：言語サポートが厚く・パースが確実
  • 迷ったらYAMLから始めて、必要になったときにJSON変換するのがおすすめ

どちらのフォーマットも相互変換できるツール（Swagger Editor など）が充実しているため、後から切り替えることも難しくありません。まずは書きやすい方で始めてみましょう。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?