SwaggerとOpenAPIの違いをわかりやすく｜Vue連携の前に整理する

※ 当ブログ「日々是事始め（コレコト）」はプロモーションを含みます。

API 連携を調べると、必ず「Swagger」と「OpenAPI」が出てきます。私は最初、この2つを別物だと思って混乱しました。結論を先に言うと、OpenAPI は「仕様（ルール）」、Swagger は「そのルールを扱うツール群や旧称」です。この区別がつくと、後のコード生成の話がスッと入ります。

※ 学習用に調べた内容を個人的にまとめたものです。文章は AI の補助を受けて作成しています。

ざっくり結論
openapi.yaml の中身を読む
Swagger UI で動かして確認する
なぜVue側でこれが嬉しいのか
もっと体系的に学ぶなら（書籍）
次に読む

ざっくり結論

言葉	正体
OpenAPI	REST API の仕様を記述するための規格（OpenAPI Specification）。中身は `openapi.yaml` / `openapi.json`
Swagger	OpenAPI を扱うツール群（Swagger UI / Editor など）の名前。歴史的に仕様そのものの旧称としても使われる

もともと「Swagger Specification」と呼ばれていた仕様が、2016年ごろに OpenAPI Specification へ名称統一されました。そのため「昔の名前＝Swagger、今の正式名＝OpenAPI」と捉えると、世の中の記事の表記ゆれにも惑わされにくくなります。

openapi.yaml の中身を読む

OpenAPI ファイルには「どんな URL に・どんなリクエストを送ると・どんな JSON が返るか」が書かれています。タスク一覧の例です。

openapi: 3.0.3
info:
  title: Task API
  version: 1.0.0
paths:
  /tasks:
    get:
      tags: [tasks]
      operationId: listTasks
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
components:
  schemas:
    Task:
      type: object
      properties:
        id:    { type: integer }
        title: { type: string }
        done:  { type: boolean }
      required: [id, title, done]

paths：エンドポイント（URL）と HTTP メソッド
operationId：その操作の名前。後でコード生成すると関数名になる
tags：操作のグループ名。コード生成では TasksApi のようなクラス名のもとになる
components.schemas：データの型。生成すると TypeScript の型になる

つまり OpenAPI ファイルは、フロントとサーバーの「共通の設計図」です。これが1枚あるだけで、後述のツールが型もクライアントも自動で吐いてくれます。

Swagger UI で動かして確認する

Swagger UI を使うと、openapi.yaml をブラウザ上で見やすく表示し、その場で API を試し打ちできます。フロント実装に入る前に「どんなレスポンスが返るのか」を目で確認できるのが大きいです。

openapi.yaml
   │  Swagger UI で表示・試し打ち
   ▼
仕様を確認
   │  OpenAPI Generator / Orval
   ▼
TypeScript の型 + API クライアントを生成
   │
   ▼
Vue から型安全に呼び出す

なぜVue側でこれが嬉しいのか

手書きで fetch していると、API のレスポンス型を自分で type 定義し直す必要があり、サーバー側の変更に追従し損ねます。OpenAPI を起点にすれば、型定義が自動・常に最新になり、存在しないフィールドを参照すると TypeScript が即エラーで教えてくれます。次の記事で実際に生成します。