API仕様書の基本

OpenAPI / Swagger とは？

OpenAPI Specification（OAS）は、 REST APIのインターフェースを記述するための業界標準仕様です。 もともとSmartBear社が開発したSwagger仕様が元になっており、 2016年にOpenAPI Initiativeに移管されました。

現在、「Swagger」はツール群（Swagger UI、Swagger Editor等）のブランド名として使われ、 仕様自体は「OpenAPI Specification」と呼ばれています。最新バージョンはOpenAPI 3.1です。

# Swagger と OpenAPI の関係
#
# Swagger 1.x → Swagger 2.0 → OpenAPI 3.0 → OpenAPI 3.1
#   (2011)        (2014)         (2017)        (2021)
#
# Swagger 2.0 以降、仕様は OpenAPI Specification に改名
# Swagger はツール群のブランド名として残っている
#
# 主な Swagger ツール:
#   - Swagger UI        → APIドキュメントのビジュアル表示
#   - Swagger Editor    → ブラウザベースの仕様書エディタ
#   - Swagger Codegen   → コード自動生成（後継: openapi-generator）

なぜAPI仕様書が必要か？

API仕様書がないと、フロントエンドとバックエンドの開発者間で認識のずれが生じ、 手戻りやバグの原因になります。仕様書があることで以下のメリットが得られます。

# 仕様書がない開発フロー（問題が起きやすい）
#
# バックエンド: API実装 → フロントエンドに口頭で説明
# フロントエンド: 「えっ、レスポンスの形変わった？」
# → 手戻り、バグ、コミュニケーションコスト増大
#
# 仕様書がある開発フロー（API-first）
#
# 1. チームで仕様書を合意
# 2. バックエンド: 仕様書どおりに実装
# 3. フロントエンド: 仕様書をもとにモック→実装
# 4. 結合テスト: 仕様書どおりか自動検証
# → 並行開発が可能、認識のずれが起きにくい

API-first 開発とは

API-first 開発とは、 実装を始める前にまずAPI仕様書を設計・合意するアプローチです。 「コードを書いてからドキュメントを書く」のではなく、 「ドキュメント（仕様書）を書いてからコードを書く」という考え方です。

# API-first 開発の流れ
#
# Step 1: API設計
#   - エンドポイント、リクエスト/レスポンスの形を決める
#   - OpenAPI仕様書としてYAMLで記述する
#
# Step 2: レビュー・合意
#   - フロント/バック/QAチームで仕様をレビュー
#   - Pull Request で変更を管理
#
# Step 3: 並行開発
#   - バックエンド: 仕様書に従ってAPI実装
#   - フロントエンド: 仕様書からモックサーバーを生成して開発
#   - QA: 仕様書からテストケースを作成
#
# Step 4: 結合・検証
#   - 実装が仕様書に準拠しているか自動検証
#   - express-openapi-validator などで自動チェック

API-first開発は、マイクロサービスやフロントエンド/バックエンド分離の プロジェクトで特に効果を発揮します。

OpenAPI仕様書の構造

OpenAPI仕様書は、いくつかの主要なセクションで構成されています。 全体の構造を把握しておきましょう。

# OpenAPI 3.0 仕様書の基本構造

openapi: "3.0.3"          # OpenAPIのバージョン（必須）

info:                      # APIのメタ情報（必須）
  title: Todo API
  version: "1.0.0"
  description: TODOアプリのREST API
  contact:
    name: API Support
    email: support@example.com

servers:                   # APIサーバーのURL
  - url: https://api.example.com/v1
    description: 本番環境
  - url: http://localhost:3000/v1
    description: 開発環境

paths:                     # エンドポイント定義（必須）
  /todos:
    get:
      summary: TODO一覧を取得
      # ... 詳細は次のレッスンで
    post:
      summary: TODOを作成
      # ...

components:                # 再利用可能なスキーマ定義
  schemas:
    Todo:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
  securitySchemes:         # 認証方式の定義
    bearerAuth:
      type: http
      scheme: bearer

security:                  # グローバルな認証設定
  - bearerAuth: []

tags:                      # エンドポイントのグループ化
  - name: todos
    description: TODO関連のAPI

openapi、info、pathsが必須フィールドです。componentsは スキーマの再利用に不可欠なので、実質的に必ず使います。

YAMLの基本

OpenAPI仕様書は通常YAMLで記述します。 JSONでも書けますが、YAMLの方が可読性が高く、コメントも書けるため広く使われています。

# YAML の基本文法

# キーと値（文字列）
title: "Todo API"
version: "1.0.0"

# ネスト（インデントはスペース2つ）
info:
  title: "Todo API"
  contact:
    name: "API Support"

# 配列
servers:
  - url: https://api.example.com
    description: 本番
  - url: http://localhost:3000
    description: 開発

# 真偽値
required: true
nullable: false

# 複数行の文字列
description: |
  これは複数行の
  説明文です。
  改行が保持されます。

# --- JSON との比較 ---

# YAML:
# paths:
#   /todos:
#     get:
#       summary: TODO一覧取得

# JSON:
# {
#   "paths": {
#     "/todos": {
#       "get": {
#         "summary": "TODO一覧取得"
#       }
#     }
#   }
# }

# YAML のメリット:
#   - コメントが書ける（# で始まる行）
#   - 波括弧やカンマが不要で読みやすい
#   - インデントで構造を表現

YAMLではインデントにタブは使えません。 必ずスペースを使い、同じ階層は同じインデント数にしてください。

まとめ

• OpenAPI SpecificationはREST APIの仕様を記述する業界標準フォーマット
• SwaggerはOpenAPIのツール群のブランド名（Swagger UI、Swagger Editor等）
• API仕様書があることで、チーム間の認識ずれを防ぎ並行開発が可能になる
• API-first開発では、実装の前にまず仕様書を設計・合意する
• OpenAPI仕様書はopenapi、info、paths、componentsで構成される
• YAMLはコメントが書けて可読性が高く、OpenAPI仕様書の記述に最適