Zenn
👻

SwaggerとOpenAPIで変わるAPI仕様書の作り方【Excelから卒業】

に公開
Excel
API
仕様書
Swagger
OpenAPI
tech

はじめに

業務の基本設計の工程で、API仕様書の作成を行っています。
現状の仕様書では、システムの簡単なシナリオを作るのみで、
実際の転送項目（パラメータやレスポンス項目）はSwaggerに記載しています。

正直なところ、API仕様書はExcel形式なので、
「もう全部Excelでまとめちゃえばいいんじゃないか？」
と考えたこともあります。

実際、Swaggerを何のために利用しているのかはあまり理解できておらず、
「AIで作った定義ファイルと成果物を合わせているだけ」という状態でした。

そこで今回、Swagger（＝OpenAPI）について改めて調べ、
なぜSwaggerを使うのか、どんな利点・制約があるのかを整理しました。

SwaggerとOpenAPIとは？

まず混乱しやすいのが、Swagger と OpenAPI の関係です。
似たような言葉ですが、正確には意味が違います。

  • OpenAPI
    HTTP APIの仕様を機械と人間の両方が読める形式で記述するための
    世界共通のフォーマット（仕様そのもの）です。
    ファイル形式は YAML または JSON が使われます。
  • Swagger
    OpenAPI仕様を扱うためのツール群の総称です。
    代表的なものは以下の通りです。
    • Swagger Editor：OpenAPIファイルを編集・プレビュー
    • Swagger UI：仕様を見やすいドキュメントに変換、実行も可能
    • Swagger Codegen：クライアントSDKやサーバースタブを自動生成

もともとこの仕様は Swagger Specification と呼ばれていましたが、
2016年に OpenAPI Specification（OAS） に名称変更されました。
現在は「仕様の名前＝OpenAPI」、「ツールの総称＝Swagger」という使い分けが一般的です。

✅ざっくりまとめ

  • OpenAPI … API仕様そのもの（世界共通ルール）
  • Swagger … OpenAPIを作成・表示・利用するためのツール群

Swaggerを使うと何が便利なのか？

API仕様書をExcelで作っていると、こんな課題が出てきます。

Excelでの課題

  1. 仕様の十分性を担保しづらい
    • Excelでは「項目名・型・説明」程度にとどまり、必須/任意、値の制約、配列構造、条件分岐などの詳細は書き漏れやすい
    • 「この情報だけで本当に実装できるのか？」が不明瞭なまま進むことがある
  2. 実装への落とし込みが難しい
    • Excelは機械可読ではないため、そのままコードやテストに反映できない
    • モックやSDK生成ができず、別作業になって二重管理が発生
  3. 更新や変更が反映しにくい
    • 実装変更があってもExcelは手作業更新
    • 更新漏れや反映の遅れで仕様と実装がズレるリスクが高い

Swagger（OpenAPI）での解決

  1. 仕様の十分性を機械可読で表現できる
    • 必須・任意、型、制約（数値範囲、文字数、正規表現）、ネストや配列構造まで正確に記述可能
    • Exampleで実際のJSONレスポンス例を提供できるため、誤解が減る
  2. 記述方法が標準化されている
    • OpenAPIは世界共通の書き方が決まっているため、誰が書いても構造が同じ
    • ツールやライブラリがその形式を前提にしているので、実装に落とし込みやすい
    • 他プロジェクトや外部とのやり取りでも互換性が高い
  3. 自動化で実装に直結できる
    • 同じ定義からクライアントSDK、サーバースタブ、モックサーバを生成可能
    • CIで仕様と実装の差異を検証でき、齟齬を早期に発見できる
  4. 更新とレビューが容易
    • YAML/JSONなので差分が明確に見える
    • Gitで履歴管理でき、誰がどの項目を変えたか追跡できる

✅ざっくりまとめ

Excelは「人が読む最低限の仕様」には向いていますが、
仕様の十分性の担保、記述の標準化、実装への直結性という点では弱いです。
Swagger（OpenAPI）は記述方法が決まっており、人間にも機械にも理解可能なため、
そのまま実装やテストに落とし込みやすい仕様書として機能します。

OpenAPIでできること・できないこと

OpenAPIはAPI仕様の世界共通フォーマットです。
記述方法が標準化されているため、人にも機械にも理解できる形式で情報を扱えます。
ただし、万能ではなく、できることとできないことがはっきりあります。

OpenAPIでできること

  1. API仕様を正確に表現

    • エンドポイントURL、HTTPメソッド
    • パラメータ（path / query / header）
    • リクエストボディの型・必須・制約
    • レスポンス構造（成功・エラー）、ステータスコード
    • サンプルデータ（Example）

  2. 人向けのドキュメント化

    • Swagger UIで見やすいAPI仕様書を自動生成
    • Exampleや型情報を表形式で確認可能

  3. 機械向けの活用

    • クライアントSDKやサーバースタブの自動生成
    • モックサーバの生成
    • スキーマバリデーション、自動テストへの組み込み

  4. 共通仕様の再利用

    • エラー形式やページネーションなどを共通スキーマ化
    • components を使って複数APIで再利用可能

  5. 環境切り替えと認証設定

    • 本番・検証・ローカル環境URLの切り替え
    • APIキー、OAuth2、JWTなどの認証方式定義

OpenAPIでできないこと

  1. 業務ロジックや処理内容の説明

    • 「条件AのときだけBを実行する」といったビジネスルール
    • 画面や処理の順序、ワークフロー図の表現

  2. 非機能要件の記載

    • SLA（応答時間保証）や性能要件
    • 同時接続数やレート制限の保証値
    • セキュリティポリシーの詳細

  3. 実装の正しさ保証

    • 定義通りに実装されているかは別途テストが必要
    • 実装が定義とずれても、OpenAPIファイル自体はエラーを出さない

  4. 複雑な条件付きルールの完全表現

    • 「フラグXがtrueならY必須」などの依存関係は限定的にしか表現できない
    • JSON Schemaの制約で一部は可能だが限界あり

  5. UIや画面の設計

    • ボタンやレイアウトなどの画面仕様は記載できない

✅ざっくりまとめ

OpenAPIはAPIインターフェースの仕様を正確かつ標準化して表すことが得意です。
逆に、業務の中身や非機能要件、画面設計のような「APIの外側の話」は別資料で補う必要があります。

まとめ

今回、業務でAPI仕様書をExcelではなくSwagger（OpenAPI）で記述する理由を調べてみて、
仕様の十分性・記述の標準化・実装への直結性という3つの面で、SwaggerはExcelよりも優れていることが分かりました。

次回は、今回の内容を踏まえて
「Swagger（OpenAPI）の具体的な使い方」 を記事にする予定です。

Discussion