Swaggerとは？書き方・使い方・OpenAPIとの違いなどを徹底解説！

API開発をしていると必ず耳にする「Swagger」という言葉。

「ドキュメントを自動生成してくれる便利なツールでしょ？」と知っている方もいれば「OpenAPIと何が違うの？」と疑問を持つ方も多いのではないでしょうか。

この記事では『Swaggerの概要や具体的な書き方』を、図やサンプルコードを用いて初心者にもわかりやすく解説します。ご参考になれば幸いです。

Swaggerとは？

Swagger（スワッガー）は、APIの仕様を定義し、共有するためのツール群（Swagger UI/Editor など）です。「APIの利用者（フロントエンドエンジニアや外部の開発者など）」と「APIを提供する側（バックエンドエンジニアやシステム設計者）」が、同じ形式でAPI仕様を理解できるようにする役割を果たします。

Swaggerで使われていた仕様は、現在ではOpenAPI Specification（OAS）として標準化されています。そのため、仕様そのものは「OpenAPI」と呼び、Swaggerはその仕様を扱うためのツール群を指します。

Swagger（ツール群）やOpenAPI（仕様）を利用することで、REST API の設計・開発・テスト・ドキュメント化を効率化でき、コードを書く前に仕様を明確にし、関係者全員が共通理解を持てるようになります。

Swaggerを使うメリット

API開発にSwaggerを導入すると、以下のようなメリットがあります。

メリット

ドキュメント自動生成
- OpenAPI（YAML/JSON）の定義を書くだけで、Swaggerが見やすいAPIドキュメントを自動生成してくれます。これにより、ExcelやWordでドキュメントを管理する必要がなくなります。
設計と実装の整合性確保
- エンドポイント、リクエスト/レスポンス、スキーマ（JSON Schema）を機械可読な形で定義できるため、フロントエンドとバックエンドの間で発生しがちな仕様のズレを減らせます。
テストが容易
- Swagger UIからブラウザ経由で直接リクエストを実行し、レスポンスを確認できます。軽量な検証に向いており、Postmanなどを準備しなくても素早く試せます。
コード生成による効率化
- 定義ファイルからサーバーの雛形コードやクライアントSDKを自動生成できます。これにより、初期実装の手間やヒューマンエラーを大幅に削減できます。かつては「Swagger Codegen」が主流でしたが、現在は機能が強化された「OpenAPI Generator」の利用が広まっています。

Swaggerの主要ツール

Swaggerには、用途に応じた複数のツールが提供されています。代表的なものを以下に示します。

Swagger Editor
- API仕様を記述するためのエディタ。
- 「Webブラウザから使えるオンライン版」と「ローカルで動かせる版」の両方がある。
- YAMLまたはJSON形式で書いたOpenAPI仕様をリアルタイムにプレビューできる。
- 記述ミスがあれば即座に検出されるため、学習やレビューにも最適。
Swagger UI
- API仕様をもとに、見やすいドキュメントを自動生成して表示するツール。
- エンジニア以外の関係者でも理解しやすい形式で表示される。
- ブラウザ上から直接リクエストを送信し、レスポンスを確認できるため、設計段階のテストにも便利。
Swagger Codegen
- OpenAPI仕様を入力として、サーバーやクライアントのコードを自動生成するツール。
- Java、Python、TypeScriptなど複数の言語・フレームワークに対応。
- 現在は後継として、より活発に開発が進むOpenAPI Generatorが広く使われている。

SwaggerでAPI仕様を記述する方法

Swaggerを使ってAPI仕様を記述する方法は、大きく分けて次の2パターンがあります。

Swagger Editorを使ってAPI仕様を記述する方法
VSCodeなどのエディタでAPI仕様を記述する方法

それぞれの特徴を解説します。

Swagger Editorを使ってAPI仕様を記述する方法

Swaggerをこれから触る初心者の方におすすめなのが、公式が提供しているSwagger Editor（オンライン版）です。特徴を以下に示します。

インストール不要で即利用可能
- 専用のアプリをインストールする必要はなく、ブラウザからSwagger Editorを開くだけで利用できます。
サンプル付きで安心
- ページを開くと、あらかじめサンプルのAPI仕様が記述された状態になっています。
- このサンプルを参考にしながら、自分のAPI仕様に書き換えていけるので、記法がわからない人でも学びやすい仕組みです。
リアルタイムプレビュー
- 左側にYAML/JSONで仕様を入力すると、右側にAPIドキュメントが即座にプレビューされます。
- 実際に利用者が目にするドキュメントを確認しながら執筆できるため、「思ったとおりに表示されない」といったミスを減らせます。
「Try it out」で簡易テスト
- Swagger UIと連携しており、「Try it out」ボタンを押すとAPIを直接実行できます。APIがまだ存在しない場合でも挙動を確認できるので、設計段階から実際の利用イメージを共有することが可能です。

とにかく「まずは書いてみたい！」というときは、このSwagger Editor（オンライン版）を使ってみましょう。

VSCodeなどのエディタでAPI仕様を記述する方法

チーム開発や本格的な管理をするなら、普段使い慣れているVisual Studio Code（VSCode）で書くのがおすすめです。

拡張機能で快適に記述
- Swagger ViewerやOpenAPI (Swagger) Editorを導入すれば、補完機能やバリデーションが効き、効率的に記述できます。
Git管理と相性抜群
- VSCode上で書いたSwaggerファイルはそのままGitリポジトリにコミットできるため、チーム全員でバージョン管理しながら共有できます。
プレビューも簡単
- VSCodeでは Ctrl + Shift + P（Macの場合は Command + Shift + P）でコマンドパレットを開き、「Preview Swagger」と入力することで、Swagger UI風にプレビューができます。API定義を確認しながら書き進められるので安心です。

私自身は普段こちらの方法を使っています。Gitと組み合わせて仕様をレビューしたり、開発メンバーと共有するにはVSCodeのほうが便利だからです。

Swaggerの書き方

Swagger（OpenAPI Specification）は、YAMLまたはJSON形式で記述します。大きな流れとしては、まず「ドキュメントの基本情報」を定義し、その後に「APIのエンドポイントやリクエスト／レスポンス」を記述していきます。

API仕様を記述する際に特に重要なのが次の3つです。

openapi : OpenAPIのバージョン
info : APIの基本情報（タイトル、説明、連絡先など）
paths : 実際のAPIのエンドポイントと、そのリクエストやレスポンスの仕様

これらはSwagger仕様の「土台」となる必須項目で、必ず定義しなければなりません。

以下にシンプルなサンプルコードを示します。

openapi: 3.0.3
info:
  title: User API                  # ✅ 必須
  description: |
    このAPIはユーザーの登録・取得・削除を行うサンプルAPIです。
    OpenAPI仕様に基づいています。
  termsOfService: https://example.com/terms
  contact:                           # Contact Object
    name: API サポートチーム
    url: https://example.com/support
    email: support@example.com
  license:                           # License Object
    name: Apache 2.0                 # ✅ 必須
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0                     # ✅ 必須

servers:
  - url: https://api.example.com/v1
    description: 本番環境
  - url: https://staging.example.com/v1
    description: ステージング環境

tags:                                # タグ定義（カテゴリ分け）
  - name: User
    description: ユーザー関連の操作

paths:
  /user/{userId}:
    get:
      tags:
        - User
      summary: ユーザー情報取得API
      description: 指定された userId のユーザー情報を返します。
      parameters:                      # パラメータ定義
        - name: userId
          in: path
          required: true
          description: 取得したいユーザーのID
          schema:
            type: integer
            format: int64
            example: 123
      responses:                       # レスポンス定義
        200:
          description: 成功時のレスポンス
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1001
                  name:
                    type: string
                    example: Taro Yamada
        404:
          description: ユーザーが見つかりません
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found

    delete:
      tags:
        - User
      summary: ユーザー削除API
      description: 指定された userId のユーザーを削除します。
      parameters:
        - name: userId
          in: path
          required: true
          description: 削除するユーザーのID
          schema:
            type: integer
            format: int64
            example: 123
      responses:
        204:
          description: 削除成功（レスポンスボディなし）
        404:
          description: ユーザーが見つかりません
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found

  /user:
    post:
      tags:
        - User
      summary: ユーザー登録API
      description: 新しいユーザーを登録します。
      requestBody:                      # POSTは requestBody を利用
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Hanako Suzuki
                email:
                  type: string
                  format: email
                  example: hanako@example.com
      responses:
        201:
          description: 登録成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 2001
                  name:
                    type: string
                    example: Hanako Suzuki
                  email:
                    type: string
                    example: hanako@example.com

上記のYAMLファイルの出力は以下のようになります。

ではこれから、Swaggerの書き方について、openapiやinfo等を順番に解説していきます。

openapi（必須）

openapiフィールドは、このAPI仕様書がどのバージョンのOpenAPI Specification（OAS）に従って書かれているかを定義する場所です。

openapi: 3.0.3

現在よく利用されているのは3.0.x系および3.1.x系です。これがないとツール側が仕様を正しく解釈できません。

info（必須）

infoフィールドは、タイトル・説明・バージョンなどAPIのメタ情報を定義する場所です。

infoには、以下の情報を記述できます。

フィールド	型	解説
`title`	string	✅ 必須。 APIのタイトル。
`description`	string	APIの詳細な説明。 Markdown記法も利用可能。
`termsOfService`	string(URL)	利用規約ページへのリンク。
`contact`	Contact Object	APIに関する連絡先情報
`license`	License Object	ライセンス情報。
`version`	string	✅ 必須。 API仕様書のバージョン。

info:
  title: User API                  # ✅ 必須
  description: |
    このAPIはユーザーの登録・取得・削除を行うサンプルAPIです。
    OpenAPI仕様に基づいています。
  termsOfService: https://example.com/terms
  contact:                           # Contact Object
    name: API サポートチーム
    url: https://example.com/support
    email: support@example.com
  license:                           # License Object
    name: Apache 2.0                 # ✅ 必須
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0                     # ✅ 必須

infoが記述されると定義書では以下のように表示されます。

contactの型（Contact Object）とlicenseの型（License Object）について次に説明します。

Contact Object（連絡先情報）

Contact Objectは、公開されるAPIに関する連絡先情報を記述するオブジェクトです。この情報を記載しておくことで、利用者は API について質問や問題報告をするときに、誰に問い合わせればよいのかがわかります。

フィールド名	型	説明
`name`	string	連絡先の「人」または「組織」の名前。
`url`	string(URI)	連絡先情報を参照できるWebページのURL。
`email`	string(email)	連絡先のメールアドレス。

License Object（ライセンス情報）

License Objectは、APIがどのライセンスで提供されているかを記述するオブジェクトです。API の利用条件を明示するために重要で、OSS のAPIでは必ず入れることが推奨されています。

フィールド名	型	説明
`name`	string	✅ 必須 APIで使われているライセンス名。
`url`	string(URI)	ライセンス文書へのURL。

paths（必須）

pathsは、APIの実際の入り口（エンドポイント）を定義する場所です。URLごとに処理内容（HTTPメソッド・パラメータ・レスポンスなど）を記述します。pathsは、下記のような階層形式で情報を記述します。

パスのURL
- 実際のエンドポイント（例: /user/{userId}）
HTTPメソッド
- get, post, put, deleteなど
HTTPメソッドのリクエストとレスポンスに関する記述
- summary, description, parameters, requestBody, responses など
- 「HTTPメソッドのリクエストとレスポンスに関する記述」については、次に詳しく説明します。

サンプルコードを以下に示します。

paths:
  /user/{userId}:                      # パスのURL
    get:                               # HTTPメソッド
      tags:
        - User
      summary: ユーザー情報取得API
      description: 指定された userId のユーザー情報を返します。
      parameters:                      # HTTPメソッドのリクエストとレスポンスに関する記述
        - name: userId
          in: path
          required: true
          description: 取得したいユーザーのID
          schema:
            type: integer
            format: int64
            example: 123
      responses:                       # HTTPメソッドのリクエストとレスポンスに関する記述
        200:
          description: 成功時のレスポンス
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1001
                  name:
                    type: string
                    example: Taro Yamada
        404:
          description: ユーザーが見つかりません
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found

HTTPメソッドのリクエストとレスポンスに関する記述

エンドポイントの中でgetやpostなどのHTTPメソッドを書いたら、その下にさらに詳しく

どんなリクエストを受け取るのか
どんなレスポンスを返すのか

を定義します。

設定できるフィールドは以下になります。

フィールド名	型	説明
`tags`	array[string]	APIを分類するタグ。 Swagger UIではカテゴリ分けに使われる。
`summary`	string	APIの概要。
`description`	string	APIの詳細な説明。
`parameters`	parameter object	リクエストに必要なパラメータ。
`requestBody`	requestBody object	リクエスト本文を定義。主に`POST`や`PUT`で利用。
`responses`	response object	✅ 必須返ってくるレスポンスを定義。成功時だけでなく、エラー（400系・500系）も書くのが推奨。
`operationId`	string	処理を一意に識別するID。コード生成時に利用される。
`security`	security requirement object	このエンドポイントに必要な認証/認可を定義。

上記において、もっとも重要であるparameters、requestBody、responsesについて次に説明します。

parameters

parametersは、APIにリクエストを送る際に必要な入力情報を定義する場所です。

例えば、「/user/{userId}のようにURLの一部に含まれるID」や「クエリパラメータとして送る値」、「ヘッダーやクッキーに渡す値」などを記述します。

parametersには、以下の情報を記述できます。

フィールド名	型	説明
`name`	string	✅ 必須。パラメータ名（例: `userId`）。
`in`	string	✅ 必須。パラメータの場所。`query`, `header`, `path`, `cookie`のいずれか。
`description`	string	パラメータの説明。
`required`	boolean	必須かどうか。 `in: path`の場合は常に`true`が必須。
`schema`	schema object	✅ 必須データ型（`string`, `integer` など）やフォーマット（例: `int64`）を指定。

paths:
  /user/{userId}:
    get:
      # ここから
      parameters:                      # パスパラメータ
        - name: userId 
          in: path                     # userIdは「/user/{userId}」のようにURLの一部に含まれるので、「in: path」を指定
          required: true               # 「in: path」なのでrequiredはtrue
          description: 取得したいユーザーのID
          schema:
            type: integer
            format: int64
            example: 123
      # ここまで

この例は、URL/user/{userId}を呼び出すときにuserIdが必須の整数値であることを定義しています。

parametersが記述されると定義書では以下のように表示されます。

requestBody

requestBodyは、APIに送信する本文データ（JSONやXMLなど）を定義する場所です。

主にPOSTやPUTなど「データを送信する系のメソッド」で使います。例えば、新しいユーザーを登録するAPIでは「ユーザー名やメールアドレス」を本文に含めて送ります。

requestBodyには、以下の情報を記述できます。

フィールド名	型	説明
`description`	string	リクエスト本文の説明
`required`	boolean	本文が必須かどうか（デフォルトは`false`）
`content`	object	✅ 必須データの形式（例: `application/json`）を指定し、その下に`schema`を記述

paths:
  /user:
    post:
      # ここから
      requestBody:                      # POSTは requestBody を利用
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Hanako Suzuki
                email:
                  type: string
                  format: email
                  example: hanako@example.com
      # ここまで

つまり/userにPOSTするときは、以下のようなJSONを送る必要があります。

{
  "name": "Hanako Suzuki",
  "email": "hanako@example.com"
}

requestBodyが記述されると定義書ではこのように表示されます。

responses

responsesは、APIが返すレスポンスを定義する場所です。返却されるHTTPステータスコードごとに記述できます。成功時（200系）だけでなく、エラー時（400系、500系）も書くことが推奨されます。

responsesには、以下の情報を記述できます。

フィールド名	型	説明
`description`	string	✅ 必須。レスポンスの説明（何が返るのか）。
`content`	schema object	データの形式（例: `application/json`）を指定し、その下に`schema`を記述
`headers`	headers object	レスポンスヘッダーを定義（例: `Content-Type`）

paths:
  /user/{userId}:
    get:
      # ここから
      responses:                       # レスポンス定義
        200:
          description: 成功時のレスポンス
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1001
                  name:
                    type: string
                    example: Taro Yamada
        404:
          description: ユーザーが見つかりません
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      # ここまで

responsesが記述されると定義書ではこのように表示されます。

【requestBodyとresponses】content内の書き方

OpenAPI 3.xでは、リクエストやレスポンスで返すデータを定義するときに、必ずcontent → Content-Type → schemaという階層で書きます。つまり、データの形式（Content-Type）をまず指定して、その中にデータの構造（schema）を定義する流れです。

ほとんどのAPIはJSON形式を返すので、多くの場合はこのように書きます。

content → application/json → schema

サンプルコード

paths:
  /user/{userId}:
    get:
      responses:
        200:
          description: 成功時のレスポンス
          content:                     # content: 返すデータの形式を指定
            application/json:          # Content-Type: 返すデータの形式を指定（ほとんどapplication/json）
              schema:                  # schema: JSONの中身の構造を定義
                type: object
                properties:
                  id:
                    type: integer
                    example: 1001
                  name:
                    type: string
                    example: Taro Yamada

値の受け渡し方（GETはparameters、POSTはrequestBodyに書く）

APIでは、HTTPメソッドによってデータの渡し方が違います。Swaggerでもこの違いをきちんと表現する必要があります。

GETの場合

データ取得系（一覧取得や検索など）
データはURLの外側に付与する
- クエリパラメータ（例: /user?userId=123）
- パスパラメータ（例: /user/{userId}）
Swaggerではparametersに書く

paths:
  /user/{userId}:
    get:
      # ここから
      parameters:                      # GETメソッドで渡すパラメータ定義
        - name: userId 
          in: path                     # 「in: path」なのでパスパラメータ
          required: true
          description: 取得したいユーザーのID
          schema:
            type: integer
            format: int64
            example: 123
      # ここまで

POSTの場合

データ登録・更新系（新規作成や送信など）
データはリクエスト本文（body）に入れる
SwaggerではrequestBodyに書く

paths:
  /user:
    post:
      requestBody:                      # POSTは requestBody を利用
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Hanako Suzuki
                email:
                  type: string
                  format: email
                  example: hanako@example.com

【注意点】POSTでもパスパラメータやクエリパラメータはparametersに書く

POSTの場合、入力データは基本的にrequestBodyに書きます。ただし、「URLの一部に含まれるパスパラメータ（例: /users/{userId}）」や「クエリパラメータとして送る値」、「ヘッダーやクッキーに渡す値」は例外です。必ずparametersに書く必要があります。

つまり、POSTではparametersとrequestBodyが共存するケースがあります。

/user/{userId}:
  post:
    summary: ユーザーに投稿を追加するAPI
    parameters:                    # パスパラメータ
      - name: userId
        in: path
        required: true
        description: 対象ユーザーのID
        schema:
          type: integer
          format: int64
          example: 123
    requestBody:                   # 本文データ
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                type: string
                example: Hanako Suzuki
              email:
                type: string
                format: email
                example: hanako@example.com

schemaについて

Swagger（OpenAPI）では、parameters / requestBody / responsesを記述する際にschemaを使ってデータの型や構造を定義します。このschemaにはschema Objectを記述します。イメージとしてはJSONデータの設計図です。データがどんな型か、JSONの構造、値の例（example）を指定できます。

JSONの構造とschemaの対応表を以下に示します。

JSONの形	schemaの書き方	例（返るJSON）
文字列 (string)	`type: string`	`"hello"`
数値 (integer)	`type: integer`	`123`
数値 (number)	`type: number`	`12.34`
真偽値 (boolean)	`type: boolean`	`true`
オブジェクト {}	`type: object` + `properties`	`{ "id": 1, "name": "Taro" }`
配列 []（文字列）	`type: array` + `items: { type: string }`	`[ "a", "b", "c" ]`
配列 []（オブジェクト）	`type: array` + `items: { type: object, properties: ... }`	`[ { "id": 1 }, { "id": 2 } ]`

JSONの構造がオブジェクトや配列の場合には、以下のように、propertiesやitemsを必ず書く必要があるので注意してください。

オブジェクト{}
- type: objectを指定して、その中にpropertiesを書く
配列[]
- type: arrayを指定して、その中にitemsを書く

type: objectの場合

オブジェクトを表すときはpropertiesを使います。propertiesには基本的に下記3つが記述されていれば動作します。

フィールド名	型	説明
`type`	string	✅ 必須。データ型（`string`, `number`, `boolean`, `array`, `object`など）
`format`	string	型のフォーマット（`int64`, `date-time`など）
`example`	typeで指定した型	サンプル値（ドキュメント表示用）

サンプルコードを以下に示します。

responses:
  200:
    description: success operation
    content:
      application/json:
        schema:
          type: object
          properties:
            data:
              type: string
              example: hello

上記のように記述すると、返却されるJSONは以下のようになります。

{
  "data": "hello"
}

type: arrayの場合

配列を表すときはitemsを使います。配列の要素がどんな型かをitemsに書きます。

配列が文字列の場合のサンプルコードを以下に示します。

responses:
  200:
    description: success operation
    content:
      application/json:
        schema:
          type: array
          items:
            type: string

上記のように記述すると、返却されるJSONは以下のようになります。

[
  "apple",
  "banana",
  "cherry"
]

配列がオブジェクトの場合のサンプルコードを以下に示します。

responses:
  200:
    description: success operation
    content:
      application/json:
        schema:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                example: 1
              name:
                type: string
                example: Taro

上記のように記述すると、返却されるJSONは以下のようになります。

[
  {
    "id": 1,
    "name": "Taro"
  },
  {
    "id": 2,
    "name": "Hanako"
  }
]

servers（任意）

serversは、APIがどこで動いているか（ベースURL）を定義する場所です。Swagger UIなどのツールで「どの環境のAPIを叩くか」を切り替えるために使います。

APIは本番だけでなく、開発環境やステージング環境でも利用されます。そのため、複数のURLをserversに書いておけば、利用者はドキュメント上で環境を切り替えてリクエストを送れるようになります。

serversには、以下の情報を記述できます。

フィールド	型	解説
`url`	string	✅ 必須サーバーのベースURL。変数を含めることも可能（例: `https://{env}.example.com`）。
`description`	string	サーバーの説明。どの環境かを説明する用途に使用。
`variables`	object	URL内で使う変数を定義（環境ごとに差し替えられる）

servers:
  - url: https://development.example.com
    description: Development server
  - url: https://staging.example.com
    description: Staging server
  - url: https://api.example.com
    description: Production server

これにより、Swagger UI上では、プルダウンでDevelopment / Staging / Productionを選んで実行できるようになります。

URLに変数を使う場合のサンプルコードを以下に示します。

servers:
  - url: https://{env}.example.com
    description: サーバー環境を切り替え可能
    variables:
      env:
        default: dev
        enum:
          - dev
          - staging
          - prod

こう書くとhttps://dev.example.comやhttps://staging.example.comに切り替えられます。

tags（任意）

tagsは、APIをカテゴリごとに整理するための仕組みです。API の数が多くなるとドキュメントが長くなり、目的のエンドポイントを探しにくくなります。そんなときに tags を設定しておくと、

「ユーザー関連」
「商品関連」
「注文関連」

といったグループにまとめて表示できるようになります。

Swagger UIではタグごとに折りたたみ表示されるため、必要なカテゴリだけ開いて確認できて便利です。

書き方は簡単です。まず、全体にタグを定義します。

tags:                                # タグ定義（カテゴリ分け）
  - name: User
    description: ユーザー関連の操作
  - name: Product
    description: 商品関連の操作

そして実際のエンドポイントにタグを付与します。

paths:
  /user/{userId}:
    get:
      tags:
        - User                     # タグを付与
      summary: ユーザー情報取得API
      description: 指定された userId のユーザー情報を返します。

こうしておくと、Swagger UIではUserやProductといったカテゴリごとに API が表示されるようになります。大規模なAPIでも章立てのように整理され、利用者にとって見やすく理解しやすいドキュメントになります。

componentsで共通記述をまとめる方法

APIの仕様が大きくなると、同じパラメータやレスポンスを何度も書くことになります。これではYAMLが冗長になり、修正時に全てを書き直さなければならず保守が大変です。

そこで登場するのがcomponentsです。componentsは共通して使う部品（schemas・parameters・responsesなど）を定義しておき、必要なときに$ref（参照）で呼び出せる仕組みです。

まとめられる主な項目

schemas（データモデル）
parameters（共通パラメータ）
responses（共通レスポンス）
requestBodies（共通リクエスト本文）
headers（共通レスポンス/リクエストヘッダー）
securitySchemes（セキュリティ設定）

components.schemas（データモデル）

もっともよく使うのがcomponents.schemasです。例えば「ユーザー」というデータ構造を1箇所に定義し、複数のAPIから参照できます。

定義例

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 1001
        name:
          type: string
          example: Taro Yamada

参照方法

/user/{userId}:
  get:
    tags:
      - User
    summary: ユーザー情報取得API
    responses:
      200:
        description: 成功時のレスポンス
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'

$refを使うことで、Userスキーマをそのまま参照できます。定義を1箇所にまとめられるので、仕様変更（フィールド追加など）があってもcomponents側を直すだけでOKです。

components.parameters（共通パラメータ）

例えば多くのAPIに共通するpageやlimitのようなクエリパラメータは、components.parametersにまとめておくと便利です。

定義例

components:
  parameters:
    UserIdParam:
      name: userId
      in: path
      required: true
      description: 取得したいユーザーのID
      schema:
        type: integer
        format: int64
        example: 123

参照方法

paths:
  /user/{userId}:
    get:
      tags:
        - User
      summary: ユーザー情報取得API
      parameters:
        - $ref: '#/components/parameters/UserIdParam'

これで「共通パラメータ」を1箇所に集約できます。もしUserIdParamを変更したいときも、components側を直すだけで全体に反映されます。

components.responses（共通レスポンス）

同じエラーレスポンスをいくつものAPIに書くのは大変です。そこで共通レスポンスをcomponents.responsesにまとめておきます。

定義例

components:
  responses:
    NotFound:
      description: ユーザーが見つかりません
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Not Found

参照方法

paths:
  /user/{userId}:
    get:
      tags:
        - User
      summary: ユーザー情報取得API
      responses:                       # レスポンス定義
        404:
          $ref: '#/components/responses/NotFound'

共通エラーを定義しておくと、API全体の統一感が出て利用者も理解しやすくなります。

なお、冒頭に記述したAPI仕様において、componentを用いると以下のようになります。

openapi: 3.0.3
info:
  title: User API
  description: |
    このAPIはユーザーの登録・取得・削除を行うサンプルAPIです。
    OpenAPI仕様に基づいています。
  termsOfService: https://example.com/terms
  contact:
    name: API サポートチーム
    url: https://example.com/support
    email: support@example.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0

servers:
  - url: https://api.example.com/v1
    description: 本番環境
  - url: https://staging.example.com/v1
    description: ステージング環境

tags:
  - name: User
    description: ユーザー関連の操作

paths:
  /user/{userId}:
    get:
      tags:
        - User
      summary: ユーザー情報取得API
      description: 指定された userId のユーザー情報を返します。
      parameters:
        - $ref: '#/components/parameters/UserIdParam'
      responses:
        200:
          $ref: '#/components/responses/UserResponse'
        404:
          $ref: '#/components/responses/NotFoundResponse'

    delete:
      tags:
        - User
      summary: ユーザー削除API
      description: 指定された userId のユーザーを削除します。
      parameters:
        - $ref: '#/components/parameters/UserIdParam'
      responses:
        204:
          $ref: '#/components/responses/DeleteNoContentResponse'
        404:
          $ref: '#/components/responses/NotFoundResponse'

  /user:
    post:
      tags:
        - User
      summary: ユーザー登録API
      description: 新しいユーザーを登録します。
      requestBody:
        $ref: '#/components/requestBodies/UserCreateRequest'
      responses:
        201:
          $ref: '#/components/responses/UserCreatedResponse'

# 共通部品を定義
components:
  parameters:
    UserIdParam:
      name: userId
      in: path
      required: true
      description: ユーザーID
      schema:
        type: integer
        format: int64
        example: 123

  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 1001
        name:
          type: string
          example: Taro Yamada
        email:
          type: string
          format: email
          example: taro@example.com
    UserCreate:
      type: object
      properties:
        name:
          type: string
          example: Hanako Suzuki
        email:
          type: string
          format: email
          example: hanako@example.com
    Error:
      type: object
      properties:
        error:
          type: string
          example: Not Found

  requestBodies:
    UserCreateRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserCreate'

  responses:
    UserResponse:
      description: ユーザー情報取得成功
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'
    UserCreatedResponse:
      description: ユーザー登録成功
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'
    DeleteNoContentResponse:
      description: 削除成功（レスポンスボディなし）
    NotFoundResponse:
      description: ユーザーが見つかりません
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

本記事のまとめ

この記事では『Swagger』について、以下の内容を説明しました。

Swaggerとは？
- Swaggerを使うメリット
- Swaggerの主要ツール
SwaggerでAPI仕様を記述する方法
- Swagger Editorを使ってAPI仕様を記述する方法
- VSCodeなどのエディタでAPI仕様を記述する方法
Swaggerの書き方
- openapi（必須）の書き方
- info（必須）の書き方
  - Contact Object（連絡先情報）の書き方
  - License Object（ライセンス情報）の書き方
- paths（必須）の書き方
  - HTTPメソッドのリクエストとレスポンスに関する記述
    - parametersの書き方
    - requestBodyの書き方
    - responsesの書き方
    - 【requestBodyとresponses】content内の書き方
    - 値の受け渡し方（GETはparameters、POSTはrequestBodyに書く）
    - schemaについて
      - type: objectの場合
      - type: arrayの場合
- servers（任意）の書き方
- tags（任意）の書き方
componentsで共通記述をまとめる方法
- components.schemas（データモデル）
- components.parameters（共通パラメータ）
- components.responses（共通レスポンス）

お読み頂きありがとうございました。