Zenn
🔖

Swagger Editor と Swagger UI は何が違う？用途を分かりやすく解説

に公開
API
設計
仕様書
Swagger
OpenAPI
tech

はじめに

前回は「Swaggerとは？」を整理しました。
今回はさらに踏み込んで、Swaggerの代表的なツールである
Swagger Editor と Swagger UI の違いをまとめます。

Swagger Editor とは？

  • OpenAPI（YAML/JSON）の定義を編集・プレビューできるツール
  • ブラウザ上で動作し、左にコード、右にプレビューという構成
  • 開発者（設計者）が仕様を書くときに利用
  • 公式サイトでも利用可能 https://editor.swagger.io
    Swagger Editorのイメージ

Swagger Editorで定義する主なエリア

基本情報エリア（info / servers）

  • API全体のタイトルや説明、バージョン
  • 利用するサーバーのURL（本番・ステージングなど）
info:
  title: User API
  version: 1.0.0
  description: ユーザー管理用のAPI
servers:
  - url: https://api.example.com
    description: 本番環境

パスエリア（paths）

  • 実際のエンドポイント（URLごと）の処理を定義
  • HTTPメソッド（GET / POST / PUT / DELETEなど）ごとに書く
  • リクエストのパラメータやレスポンスの形式もここに記載
paths:
  /users/{id}:
    get:
      summary: ユーザー取得
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 正常応答

エラー定義エリア（responses 共通化）

  • よく使うエラー（400/401/404など）を共通化して再利用
  • 実際のレスポンス例（Example）をここにまとめておくと便利
components:
  responses:
    NotFoundError:
      description: リソースが見つかりません
      content:
        application/json:
          example:
            code: NOT_FOUND
            message: 指定されたIDは存在しません

スキーマエリア（components/schemas）

  • リクエストやレスポンスのデータ型を定義
  • 配列、オブジェクト、必須項目、制約などをここにまとめる
  • 他のエリアから $ref で呼び出すとDRY（繰り返し削減）
components:
  schemas:
    User:
      type: object
      required: [id, name]
      properties:
        id:
          type: string
        name:
          type: string
        age:
          type: integer
          minimum: 0

主なエリアまとめ

  • 基本情報エリア … API全体の概要やサーバー先
  • パスエリア … エンドポイントごとの定義（メソッド・パラメータ・レスポンス）
  • エラー定義エリア … 共通エラーやレスポンスの再利用
  • スキーマエリア … データ構造を共通化して整理

Swagger UI とは？

  • OpenAPIファイルを「誰でも読める仕様書」に変換するビューア
  • 特徴は 「Try it out」 機能で、ドキュメントから直接APIを実行できる点
  • QAやフロントエンド、ビジネスサイドの人も理解しやすい
  • 実装済みのAPIサーバに組み込んで、/docs で公開するのが一般的

Swagger Editor のプレビューとSwagger UI

Swagger Editor のプレビューとSwagger UIは見た目が似ているのですが、
目的や機能が違うので比較しながらまとめていきます。

Swagger Editorのプレビュー

  • 目的 : YAML/JSONで書いたOpenAPIが正しく解釈できているかを、その場で確認するため
  • 機能 :
    ・仕様の構造をドキュメント風に表示
    ・どこにエラーがあるかリアルタイムでチェック
  • 制約 :
    ・あくまで「書く人（開発者）」向け
    ・シンプルなプレビューが中心で、実際の運用を想定した見せ方ではない
    ・認証や複雑な実行環境設定はできない

Swagger UI

  • 目的 : 完成したOpenAPIを「関係者に公開する仕様書＋実行環境」として使うため
  • 機能 :
    ・仕様を綺麗に整えたドキュメント表示
    ・「Try it out」 機能で実際にAPIを呼び出せる
    ・認証（APIキーやJWT）の入力や環境切り替え（本番/検証）のサポート
  • 対象 : 開発者だけでなく、QA、フロントエンド、ビジネスサイドも含めた幅広い利用者

違いまとめ

  • Editorのプレビュー : 編集者向けの簡易ビュー（書くための補助）
  • Swagger UI : 関係者全員に公開する正式ビュー（読む・試すため）

Swagger Editor と Swagger UI の違い

項目 Swagger Editor Swagger UI
主な用途 OpenAPIを書く・編集する OpenAPIを読む・試す
対象 開発者（設計者） 開発者・利用者・QA・ビジネス側
機能 コード補完、リアルタイムプレビュー ドキュメント化、Try it out（実行）
利用方法 ローカルや公式サイトで使う サーバに組み込み、共有・公開

まとめ

  • Swagger Editor は 書くためのツール
  • Swagger UI は 読む・試すためのツール
  • 両方を組み合わせることで、Excel仕様書では難しかった
    最新性・統一性・共有性 が実現できます。

次回は、Swagger Editorを使って実際にOpenAPIを記述する手順をサンプル付きで解説する予定です。

Discussion