【Docker簡単構築】Swagger UIをローカル環境に最速で立ち上げる手順：プロが実践する超高速API開発ワークフロー
こんにちは。テックリードの私だ。
APIファースト開発において、Swagger UI（OpenAPI）の立ち上げに毎度数分以上かけていないか？「Node.jsの環境汚染」「CORSエラーの無限ループ」「バージョンのミスマッチ」……。そんな不毛な環境構築の泥沼にハマるのは、今日で終わりにしよう。
今回は、Dockerと`docker-compose`を用いて、ローカル環境に30秒でSwagger UIを降臨させ、ホスト側のOpenAPI定義ファイルをリアルタイムでホットリロードさせる極限のワークフローを伝授する。
さらに、日々の開発スピードを10倍に跳ね上げ、チーム全体の生産性を底上げするための「隠れた設定テクニック」や「ベストプラクティス」も余すことなく共有しよう。
—
1. なぜ「Docker + Swagger UI」なのか？（圧倒的メリット）
手元にAPIドキュメントを表示させるだけなら、オンラインエディタ（Swagger Editor）やVS Codeの拡張機能でもいい。しかし、実務の現場でDockerコンテナとして立ち上げるべき決定的な理由がある。
1. 環境依存の完全排除: チームメンバー全員が、OS（Mac/Linux/Windows）の違いを意識せず、全く同一のドキュメントビューアを数秒で起動できる。
2. CORS（Cross-Origin Resource Sharing）の完全制覇: ローカルで稼働するモックサーバーや開発中API（`http://localhost:8080` など）に対して、Swagger UIから直接リクエストを飛ばす際、コンテナ間・同一オリジンに近い挙動でCORSの悩みを最小化できる。
3. オフライン開発への完全対応: ネットワーク環境に依存せず、飛行機の中やセキュリティが厳しいクローズドな環境でも完全に動作する。
—
2. 最速構築：docker-compose.yml の神構成
まずはプロジェクトルートに作業ディレクトリを切り、コンテナを定義する。
ここで紹介する `docker-compose.yml` は、単に公式イメージを動かすだけではない。ホスト側のYAMLファイルをマウントし、ファイル変更を即座にUIへ反映（ホットリロード）させるための決定版だ。
プロジェクトディレクトリ構成
my-api-project/
├── docker-compose.yml
└── openapi/
└── openapi.yaml <-- ここにOpenAPI定義を書く
`docker-compose.yml`
version: ‘3.8’
services:
swagger-ui:
image: swaggerapi/swagger-ui:v5.11.0 # 本番運用を見据え、タグは必ず固定する
container-name: swagger-ui-local
ports:
- “8080:8080”
environment:
# ホスト側のopenapi.yamlをコンテナ内のどこにマウントするかを指定
- SWAGGER_JSON=/usr/share/nginx/html/openapi.yaml
# UI側の実用的な設定
- DISPLAY_OPERATION_ID=true # オペレーションIDを表示（コード生成との紐付けに必須）
- DEFAULT_MODELS_EXPAND_DEPTH=1 # モデルスキーマの展開深度を適切に制御
- DOC_EXPANSION=list # デフォルトでエンドポイントをリスト表示（noneだと毎回開く手間がかかる）
- PERSIST_AUTHORIZATION=true # リロードしてもAPIキーやBearerトークンを保持する（神設定）
volumes:
# ローカルの定義ファイルをコンテナ内に直結
- ./openapi/openapi.yaml:/usr/share/nginx/html/openapi.yaml
restart: unless-stopped
> 💡 プロの技：環境変数の妙
> `PERSIST_AUTHORIZATION=true` は絶対に入れろ。これがないと、ページをリロードするたびにOAuth2やBearerトークンを再入力させられる。開発効率が劇的に変わる隠し味だ。
—
3. ハンズオン：最速で立ち上げてUIを確認する全手順
百聞は一見にしかず。手を動かして30秒で環境を自分のものにしよう。
Step 1: 最小限のOpenAPI定義を作成する
`openapi/openapi.yaml` を作成し、以下のコードをそのまま貼り付けろ。
openapi: 3.0.3
info:
title: 爆速API開発デモ
version: 1.0.0
description: Dockerで構築されたローカルSwagger UIのテスト用定義
servers:
- url: http://localhost:3000/v1
description: ローカルモックサーバー
paths:
/healthz:
get:
summary: ヘルスチェック
operationId: checkHealth
responses:
‘200’:
description: OK
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: UP
Step 2: Dockerコンテナを起動する
ターミナルを開き、`docker-compose.yml` があるディレクトリで以下のコマンドを叩く。
docker compose up -d
(※古い環境の場合は `docker-compose up -d`)
Step 3: ブラウザでアクセスする
ブラウザを開き、`http://localhost:8080` にアクセスせよ。
見慣れた、しかし美しく洗練されたSwagger UIが即座に立ち上がり、先ほど記述した `/healthz` エンドポイントが鎮座しているはずだ。
—
4. チーム開発を加速させる実践的ベストプラクティス
ここからが本題だ。単に動く環境を作っただけでは、シニアエンジニアとは言えない。チーム全体の生産性を極限まで引き上げるための「実務知見」を授ける。
① 巨大なYAMLを分割する「$ref」の極意
エンドポイントが増えてくると、数千行の単一YAMLファイルはメンテ不能のゴミクズと化す。OpenAPIの仕様である `$ref` を使い、コンポーネント（スキーマやレスポンス）を完全に分割せよ。
推奨ディレクトリ構成:
openapi/
├── openapi.yaml # ルート（pathsとinfoのみ記述）
└── components/
├── schemas/
│ ├── user.yaml # ユーザーモデル
│ └── error.yaml # 共通エラーモデル
└── responses/
└── 400.yaml # 共通レスポンス
ただし、ここで注意が必要だ。Swagger UIやバリデーターによっては、ファイル分割された `$ref` の解決（Bundling）が必要になる。CI/CDパイプラインやビルド時には、`@redocly/cli` などのツールを使って1つのファイルにバンドル（結合）するフローを必ず組み込め。
Redocly CLIで分割ファイルを1つに結合するビルドコマンドの例
npx @redocly/cli bundle openapi/openapi.yaml -o openapi/dist/bundled.yaml
② モックサーバー（Prism）との強力な連携
Swagger UIを立ち上げたなら、隣のタブでモックサーバーを同時に動かすのがモダンな開発スタイルだ。Stoplight社の `Prism` を使えば、定義したYAMLから一瞬でモックAPIを生やせる。
docker-compose.ymlに追加する神サービス
prism:
image: stoplight/prism:5.4.0
container-name: prism-mock-server
ports:
- “3000:4000”
volumes:
- ./openapi/openapi.yaml:/tmp/openapi.yaml
command: mock -h 0.0.0.0 /tmp/openapi.yaml
これによって、バックエンドの実装が1行も終わっていなかったとしても、フロントエンドチームはSwagger UIから「動くモックAPI」に対してリクエストを送り、レスポンスの検証を今すぐ始められる。これぞAPIファーストの真髄だ。
—
5. まとめ：今日から始めるAPI開発の高速化
今回の手順をまとめよう。
1. Docker (`swaggerapi/swagger-ui`) を使い、環境依存のないビューアを30秒で構築。
2. ボリュームマウントと環境変数（`PERSIST_AUTHORIZATION`など）で、開発体験を極限まで最適化。
3. Prismなどのモックサーバーを組み合わせ、バックエンド・フロントエンドのパラレル開発を実現。
環境構築に時間を奪われる時代は終わった。
洗練されたツールチェーンをサクッと立ち上げ、君は「真に価値のあるビジネスロジックのコードを書くこと」に集中してほしい。
プロのエンジニアとしての誇りを持って、チームの開発スピードを圧倒的な高みへ引き上げてくれ。健闘を祈る！