SwaggerでAPIドキュメントがラクになる！初心者向け完全ガイド

こんにちは、とまだです。

APIドキュメントを作るとき、「どう書けばいいか分からない」「更新が面倒」と感じたことはありませんか？

多くの開発現場で、同じような悩みを抱えています。

今回は現役のエンジニア、そして元プログラミングスクール講師としての経験から、Swaggerを使ったAPIドキュメント作成について解説します。

Swaggerとは？レストランのメニュー表をイメージしよう

Swaggerは、APIの仕様書を作るためのツールです。

レストランのメニュー表を想像してください。

料理の名前、値段、材料が一覧で見られますよね。

同じように、APIの機能、使い方、返ってくるデータを一覧にまとめたものがSwaggerです。

OpenAPIとの関係を整理

よく混同されるのが、SwaggerとOpenAPIの違いです。

簡単に言うと：

• OpenAPI：メニュー表の書き方ルール
• Swagger：メニュー表を作る道具

OpenAPIという共通ルールがあるから、誰でも読みやすいドキュメントが作れるのです。

現在はOpenAPI 3.1が最新版で、より柔軟な記述ができるようになりました。

なぜSwaggerが必要なの？3つの困った場面

APIドキュメントがないと、こんな問題が起きます。

1. チーム内での認識のズレ

「このAPIで何が返ってくるの？」

「パラメータは必須？任意？」

こんな質問が飛び交い、開発が止まってしまいます。

2. 仕様変更の伝達ミス

APIを変更したとき、全員に伝えるのは大変です。

メールやチャットで共有しても、見落としが発生します。

3. 新メンバーの学習コスト

新しく参加したメンバーが、APIの全体像を把握するのに時間がかかります。

ドキュメントが散らばっていると、さらに大変です。

Swaggerで変わる開発風景

Swaggerを導入すると、開発がこう変わります。

ブラウザで確認できる見やすいドキュメント

WordやExcelではなく、ブラウザで確認できます。

検索もしやすく、すぐに必要な情報にアクセスできます。

実際にAPIを試せる

ドキュメント上で、実際にAPIを呼び出せます。

「このパラメータを送ったら、どんなデータが返ってくるか」がすぐ分かります。

自動でコード生成

API仕様から、各プログラミング言語のコードを自動生成できます。

手作業でのミスが減り、開発スピードが上がります。

3つの主要ツールの使い分け

Swaggerには主要なツールが3つあります。

それぞれの役割を理解して、使い分けましょう。

Swagger Editor：仕様を書く

ブラウザ上でAPI仕様を書けるエディタです。

リアルタイムでプレビューが見られるので、書きながら確認できます。

Swagger UI：見やすく表示

書いた仕様を、きれいなドキュメントとして表示します。

実際にAPIを試すボタンも付いているので、動作確認も簡単です。

Swagger Codegen：コードを生成

仕様からプログラムのひな形を作ります。

手作業でコードを書く手間が省けます。

実際に動かしてみよう（Node.js編）

理論だけでは分かりにくいので、実際に動かしてみましょう。

Node.jsとExpressを使った簡単な例を紹介します。

まず、必要なパッケージをインストールします。

npm install express swagger-ui-express

次に、サーバーのコードを書きます。

// index.js
const express = require("express");
const app = express();
const port = 3000;

// Swagger UIを使うための設定
const swaggerUi = require("swagger-ui-express");
const swaggerDocument = require("./swagger.json");

// JSONリクエストを受け取れるようにする
app.use(express.json());

// Swagger UIを "/api-docs" で公開
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerDocument));

// サンプルAPI：ユーザー一覧を返す
app.get("/users", (req, res) => {
  res.json([
    { id: 1, name: "田中" },
    { id: 2, name: "佐藤" },
  ]);
});

app.listen(port, () => {
  console.log(`http://localhost:${port} でサーバー起動中`);
});

このコードのポイントは、swagger.jsonという設定ファイルを読み込んでいる部分です。

このファイルにAPI仕様を書きます。

API仕様の書き方

swagger.jsonの中身はこんな感じです。

{
  "openapi": "3.1.0",
  "info": {
    "title": "ユーザー管理API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "ユーザー一覧を取得",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/User"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          }
        }
      }
    }
  }
}

これでサーバーを起動してhttp://localhost:3000/api-docsにアクセスすると、きれいなドキュメントが表示されます。

よくある質問と解決策

Q: JSONで書くのが難しそう...

A: YAMLという形式でも書けます。

JSONより読みやすく、インデントで構造を表現できます。

Q: 既存のAPIにSwaggerを導入できる？

A: もちろん可能です。

少しずつドキュメント化していけば大丈夫です。

全部一度にやる必要はありません。

Q: どのツールから始めればいい？

A: まずSwagger UIでドキュメントを見る体験から始めましょう。

その後、Editorで仕様を書いてみるのがおすすめです。

実務で成功するための4つのコツ

1. 小さく始める

最初から完璧を目指さず、1つのAPIから始めましょう。

慣れてきたら範囲を広げていきます。

2. チームで運用ルールを決める

誰がいつ更新するか、ルールを決めておきます。

APIを変更したら必ず更新する、という習慣が大切です。

3. Gitで管理する

OpenAPIファイルもコードと同じようにGitで管理します。

変更履歴が残るので、いつ何が変わったか分かります。

4. 定期的にレビューする

古い情報が残っていないか、定期的にチェックします。

使われなくなったAPIは削除しましょう。

導入時の注意点

ファイルが大きくなりすぎる問題

APIが増えると、1つのファイルでは管理しきれません。

その場合は、機能ごとにファイルを分割します。

ツールのバージョン問題

OpenAPIのバージョンによって、使えるツールが変わります。

事前に互換性を確認しておきましょう。

自動生成コードの限界

生成されたコードはあくまでひな形です。

ビジネスロジックは自分で実装する必要があります。

まとめ

SwaggerはAPIドキュメントを楽にする強力なツールです。

レストランのメニュー表のように、APIの機能を分かりやすく整理できます。

導入のハードルは高くありません。

まずは1つのAPIから始めて、徐々に広げていけば大丈夫です。

開発チームのコミュニケーションが改善され、新メンバーの学習も楽になります。

ぜひ実際に触ってみて、その便利さを体感してください。