--- title: "Swaggerとは：Editor・UIをDockerで動かす手順とOpenAPI 3.2対応の現況" url: "https://www.issoh.co.jp/tech/details/17451/" published: 2026-09-07 updated: 2026-09-07 categories: ["アーキテクチャ"] publisher: "株式会社一創" --- # Swaggerとは：Editor・UIをDockerで動かす手順とOpenAPI 3.2対応の現況 Swaggerという言葉は、API仕様の記述形式を指す場面と、その形式を扱うツール群を指す場面の両方で使われます。検索して出てくる解説の多くは前者の説明で止まり、手元で何をどう起動すればよいかまで届きません。この記事では、swagger-uiのDockerイメージを起動するところから始め、OpenAPI 3.2.0の定義ファイルを書き、クライアントコードを生成し、CIで検査を回すところまでを、そのまま実行できるコマンドで進めます。あわせて、Swagger CodegenとOpenAPI Generatorのどちらを選ぶか、本番環境でUIをどう閉じるかという運用側の判断も示します。 ## まとめ：Swaggerの結論と3つのツールの使い分け 先に結論を置きます。 - **仕様の名前は「OpenAPI」、ツール群の名前が「Swagger」**です。2016年に仕様がOpenAPI Specificationへ改称され、SmartBearが開発するEditor・UI・Codegenといった実装側がSwaggerの名前を引き継ぎました。 - **現行の仕様は OpenAPI 3.2.0（2025年9月19日発行）**で、Swagger UI・Swagger Client・Swagger Editor・ApiDOMがこれに対応したのは2026年4月10日の発表時点です。手元の定義ファイルを新しく書き起こすなら 3.1 系か 3.2 系を選びます。 - **手を動かす最短路はDocker**です。`docker run -p 80:8080 docker.swagger.io/swaggerapi/swagger-ui` の1行でUIが立ち上がり、`SWAGGER_JSON` 環境変数でローカルの定義ファイルをそのまま読ませられます。Node.jsのバージョン整合に悩む必要がありません。 - **コード生成は OpenAPI Generator を選びます**。Swagger Codegen の安定版 3.0.71 の対応仕様は 3.0 までで、3.1 系の定義ファイルを読ませても通りません。OpenAPI Generator 7.25.0 は 3.1 をbetaとして扱う対応表を公開しています。 - **定義ファイルはCIで検査します**。Spectralによるlintと、生成コードの差分検知を1つのワークフローに入れておくと、定義とコードのずれがレビュー前に止まります。 用語そのものの整理を先に済ませたい場合は、[OpenAPIとは｜Swaggerとの違い・仕様書の書き方とSwagger UI](https://www.issoh.co.jp/tech/details/10408/)で仕様側の位置づけを確認してから戻ってくると、以降のコマンドの意味が取りやすくなります。 ## Swaggerとは何か：仕様の呼び名とツール群の関係を切り分ける ### 2016年に仕様がOpenAPIへ移り、Swaggerはツール群の名前として残った もともとSwaggerは、RESTful APIの記述形式と、それを扱うツール群をまとめて指す名前でした。2016年に記述形式がOpenAPI Initiativeへ移管され、形式の側は OpenAPI Specification（OAS）という名前になります。ツールの側はSmartBearの手元に残り、Swagger Editor、Swagger UI、Swagger Codegenといった製品名として現在も使われています。 この分岐を踏まえると、検索でぶつかる表記のゆれは整理できます。ファイル名が `swagger.yaml` でも中身の1行目が `openapi: 3.2.0` なら、それはOpenAPI形式の定義ファイルです。逆に1行目が `swagger: "2.0"` なら、改称前の形式であるSwagger 2.0（OAS 2.0）で書かれています。どちらの世代かは、拡張子でもツール名でもなく、この1行で判別します。 ### OpenAPI 3.2.0の発行日とSwagger対応日を時系列で確認する 現行の仕様は [OpenAPI Specification v3.2.0](https://spec.openapis.org/oas/latest.html) で、発行日は2025年9月19日です。3.x系の後方互換を保ったマイナーリリースという位置づけで、`openapi` フィールドには「その文書が準拠する仕様のバージョン番号」を書くと定義されています。 ツール側の対応時期は仕様の発行と一致しません。SmartBearは[2026年4月10日の告知](https://swagger.io/blog/swagger-launches-support-for-openapi-3-2-0/)で、Swagger UI・Swagger Client・Swagger Editor・ApiDOMの4つに3.2.0対応を入れたと公表しました。同じ告知で挙げられている3.2.0の追加要素は、SSEやJSONLといった順序付きメディアタイプへの対応、タグへの`summary`・`parent`・`kind`フィールド追加による階層化、`query`メソッドと`additionalOperations`、クエリ文字列全体を1つのフィールドとして扱う`in: querystring`、そして文書自身のベースURIを宣言する`$self`の5点です。 仕様が出た日ではなく、使うツールが対応した日を基準に版を選ぶ、という順序をここで押さえておきます。定義ファイルを3.2.0で書いても、読ませる側が対応していなければ画面には何も出ません。 ## 検証環境を用意する：DockerでSwagger UIとEditorを起動する ### swagger-uiイメージを起動しブラウザで表示を確認する手順 Swagger UIは、定義ファイルを読み込んでAPIリファレンスを画面に描き、その場でリクエストを送れる画面を出すツールです。[公式リポジトリのインストール手順](https://github.com/swagger-api/swagger-ui)と[Docker Hubのイメージページ](https://hub.docker.com/r/swaggerapi/swagger-ui)には、ビルド済みイメージを取得して起動する2行が示されています。 ``` docker pull docker.swagger.io/swaggerapi/swagger-ui docker run -p 80:8080 docker.swagger.io/swaggerapi/swagger-ui ``` これでポート80にnginxが立ち、ブラウザで開くとサンプルのPetstore定義が表示されます。ホスト側の80番が埋まっているなら `-p 8080:8080` のように左側を空きポートへ振り替えます。コンテナ内の待受ポートは既定で8080です。 ### SWAGGER\_JSONで手元の定義ファイルをマウントして表示する 自分が書いた定義ファイルを読ませるには、ディレクトリをマウントして `SWAGGER_JSON` にコンテナ内のパスを渡します。公式手順に示されている形をそのまま使います。 ``` mkdir -p spec docker run -p 80:8080 \ -e SWAGGER_JSON=/spec/openapi.yaml \ -v "$(pwd)/spec:/spec" \ docker.swagger.io/swaggerapi/swagger-ui ``` ファイル名が `.yaml` でも環境変数名は `SWAGGER_JSON` のままです。ここで指定するのはホスト側のパスではなく、マウント後のコンテナ内パスである点に注意します。公式リポジトリのインストール手順で使える環境変数のうち、実務で触るものを整理します。 | 環境変数 | 役割 | | ------------------ | ------------------------- | | SWAGGER\_JSON | マウントした定義ファイルのコンテナ内パス | | SWAGGER\_JSON\_URL | 外部ホスト上の定義ファイルをURLで指定 | | BASE\_URL | 配信先の変更（例 /swagger 配下） | | PORT | コンテナ内の待受ポート（既定8080） | | EMBEDDING | X-Frame-Options の有効と無効の切替 | 社内ポータルの一部として `/swagger` 配下に置きたい場合は `BASE_URL` を、別ページへiframeで埋め込む場合は `EMBEDDING` を触ります。表示設定そのもの（初期展開の深さ、検索欄の表示、バリデータの無効化など）は、リポジトリの設定ドキュメントに一覧がある `DOC_EXPANSION`、`FILTER`、`VALIDATOR_URL` といった環境変数で指定できます。 ### Swagger Editorは書きながら検証する用途に限定して使う [Swagger Editor](https://swagger.io/open-source/swagger-editor/)は、左に定義ファイル、右にプレビューを並べて表示するエディタです。文法エラーがその場で赤く出るため、書き始めの数十行を通す用途に向いているツールです。ただし、リポジトリに置いた定義ファイルを日常的に編集する段階に入ったら、エディタ画面ではなく手元のIDEとCIの検査に主軸を移すほうが運用は安定します。理由は後述のCIの章で示します。 ## OpenAPI 3.2の定義ファイルを書いてSwagger UIで表示する ### 動作確認に使う最小構成の定義ファイルを1本作成する手順を解説する 先ほどマウントした `spec/openapi.yaml` に、在庫を1件取得するだけのAPIを書きます。3.2.0で追加された `$self` とタグの `summary` も入れてあります。 ``` openapi: 3.2.0 $self: https://api.example.com/openapi.yaml info: title: Inventory API version: 1.0.0 servers: - url: https://api.example.com/v1 tags: - name: items summary: 在庫の参照と更新 paths: /items/{itemId}: get: operationId: getItem tags: [items] summary: 在庫を1件取得する parameters: - name: itemId in: path required: true schema: type: string responses: "200": description: 取得成功 content: application/json: schema: $ref: "#/components/schemas/Item" "404": description: 対象が存在しない components: schemas: Item: type: object required: [id, name, stock] properties: id: type: string name: type: string stock: type: integer format: int32 ``` コンテナを起動し直すと、UIに `GET /items/{itemId}` が1本表示されます。`operationId` は後のコード生成でメソッド名の元になるため、ここを空欄にせず動詞で書いておくと生成物が読みやすくなります。 ### 3.2.0で増えたフィールドから実務で有効な項目を具体的に確認する 3.2.0の追加要素は、既存の定義ファイルを書き換える必要があるものではありません。効き目が出る場面を挙げます。 - **タグの階層化**：`parent` と `summary` を使うと、エンドポイントが数十本を超えた画面で章立てが崩れなくなります。管理画面用と公開用が同居する定義ファイルで効きます。 - **順序付きメディアタイプ**：SSEやJSONLで結果を流す設計を、コメントではなく定義ファイル上で表現できます。生成AIの応答を逐次返すエンドポイントを持つ案件で使います。 - **$self**：文書自身のベースURIを宣言できるため、`$ref` の相対解決が読み手の置き場所に左右されにくくなります。定義ファイルを複数に分割している場合に効きます。 逆に、既存の3.0系定義ファイルを3.2.0へ上げる作業そのものに投資対効果があるかというと、周辺ツールの対応状況しだいです。次の章で扱う生成ツールの対応表を確認してから判断します。 ## openapi-generatorでクライアントコードを生成して動作を確かめる ### 生成前にvalidateを実行して定義ファイルの誤りを解消する 生成の前に、定義ファイルが仕様に沿っているかを検査します。OpenAPI GeneratorのCLIイメージには `validate` サブコマンドがあります。 ``` docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli \ validate -i /local/spec/openapi.yaml ``` ここで出る指摘は、UIの画面では気づきにくいものが中心です。`$ref` の参照先が存在しない、必須プロパティ名がスキーマ側に無い、といった不整合が該当します。UIは壊れた参照を空欄として描いてしまうため、目視では通ってしまいます。 ### Goクライアントを生成してファイル構成と中身を確認する具体的な手順 検査が通ったら生成します。[公式READMEのDocker実行例](https://github.com/OpenAPITools/openapi-generator)と同じ形です。 ``` docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \ -i /local/spec/openapi.yaml \ -g go \ -o /local/out/go ``` `-g` に渡すジェネレータ名を差し替えると出力言語が変わります。READMEに挙がっている代表例は java、go、php、ruby、typescript、python、csharp です。`-o` の出力先には、モデル定義、APIクライアント、READMEに加えて、各言語の依存定義ファイルまで一式が出ます。 生成物の扱い方は2通りです。1つは生成物をリポジトリに含めてレビュー対象にする方法、もう1つはCIで毎回生成して成果物として配る方法です。受託開発では、発注者側のレビュー範囲を明確にできる前者を選ぶ場面が多くなります。生成物を含めた場合の差分検知はCIの章で扱います。 ## Swagger CodegenとOpenAPI Generatorのどちらを選ぶか ### 対応する仕様バージョンの差が生成ツール選定の実務上の判断軸になる コード生成には、SmartBearが公開する[Swagger Codegen](https://github.com/swagger-api/swagger-codegen)と、そこから派生した[OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator)の2つがあります。両者のREADMEに載っている対応表を並べます。 | ツールと版 | リリース日 | 対応する仕様 | | ------------------------ | ---------- | -------------- | | Swagger Codegen 3.0.71 | 2025年7月3日 | 1.0から3.0まで | | Swagger Codegen 2.4.46 | 2025年6月30日 | 1.0から2.0まで | | OpenAPI Generator 7.25.0 | 2026年8月24日 | 3.1 をbeta扱いで対応 | Swagger Codegenは3.0系と2.4系の2本立てで、対応表に記載された上限は 3.0 です。3.1 で導入された記法を含む定義ファイルを読ませる前提なら、対応表に 3.1 の記載があるOpenAPI Generatorを選びます。なお 3.2 は、本稿執筆時点でどちらの対応表にも明示がありません。生成対象の定義ファイルは 3.0 系か 3.1 系に寄せ、3.2 固有の記法は表示用の定義ファイルに限る、という分け方が現実的です。 ### 判断の言い切り：新規案件はOpenAPI Generatorを既定にする 新規に組む案件では、OpenAPI Generatorを既定に置きます。理由は対応仕様の広さに加え、CLIをDockerイメージとして配っているため、開発端末にJavaを入れずに済む点です。Swagger Codegenを選ぶのは、既存プロジェクトが2.4系のテンプレートを改造して使っており、その改造を移植する工数がリスクに見合わない場合に限ります。バージョン番号の見た目が近いために互換だと考えて混在させると、生成物の構造が変わってビルドが通らなくなります。どちらか一方に固定してください。 ## 定義ファイルの品質をCIで守る手順：lintと差分検知を組み込む ### Spectralでルールセットを適用して記述漏れを検査する手順 validateは仕様違反を見ますが、命名の一貫性や説明文の欠落までは見ません。そこを埋めるのが[Spectral](https://github.com/stoplightio/spectral)です。OpenAPI向けの既定ルールセットが同梱されています。 ``` npm install -g @stoplight/spectral-cli echo 'extends: ["spectral:oas"]' > .spectral.yaml spectral lint spec/openapi.yaml ``` 既定ルールセットは、`operationId` の重複、説明文の欠落、タグ定義の不足といった項目を指摘します。指摘が多すぎて手が止まる場合は、ルールを個別に `off` にしてから、案件で守ると決めた項目だけを段階的に戻します。 ### 生成コードの意図しない差分をCIで検知する具体的なレビュー手順 定義ファイルを直したのに生成物を更新し忘れる、という取りこぼしはレビューで見つけにくいものです。生成して差分が出たら失敗させる、という1ステップを入れておきます。 ``` name: openapi on: [pull_request] jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npm install -g @stoplight/spectral-cli - run: spectral lint spec/openapi.yaml --fail-severity warn - name: generate client run: | docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli \ generate -i /local/spec/openapi.yaml -g typescript-fetch -o /local/gen - run: git diff --exit-code gen ``` 最後の `git diff --exit-code` が、生成物とコミット済みコードのずれを検知します。定義ファイルだけを直したプルリクエストはこの行で赤くなり、生成し直すまで通りません。`--fail-severity warn` を付けると、警告レベルの指摘でもCIを止められます。 ここまで入れると、Swagger Editorの画面で目視する運用から、機械が落とす運用へ移せます。冒頭で「エディタは書き始めに限定する」と書いた理由がこれです。人の目視は指摘の見落としが避けられず、定義ファイルの本数が増えるほど破綻します。テスト側からも同じ定義ファイルを使いたい場合は、[JestとOpenAPIでAPIテストを自動化する方法](https://www.issoh.co.jp/tech/details/2273/)で、定義ファイルをテストの入力に回す構成を扱っています。 ## 受託開発でSwaggerを採用する条件と見送る場面を切り分ける ### Swaggerを採用すると判断できる実務上の3つの具体的な条件 ここは判断を言い切ります。次の3条件のいずれかに当てはまるなら、OpenAPI定義ファイルとSwagger UIを最初から前提に置いてください。 - **フロントとバックエンドの担当会社が分かれている**：口頭とスプレッドシートで詰めた仕様は、必ずどこかで食い違います。定義ファイルを唯一の合意点にすると、差分がプルリクエストとして残ります。 - **APIを社外の開発者に渡す**：発注者の取引先や協業先に接続してもらう構成では、リファレンスの提供が納品物の一部になります。定義ファイルから生成できれば、更新のたびに文書を書き直す作業が消えます。 - **エンドポイントが20本を超える見込みがある**：この規模から、手書き文書の更新漏れが検知不能になります。 ### Swaggerを見送ってよい場面と代替手段を選ぶ実務の判断基準 反対に、次の場面では定義ファイルの整備を後回しにしてかまいません。 - **単一チームが閉じたAPIを数本だけ持つ**：型定義がフロントとバックで共有されているなら、定義ファイルは二重管理になります。 - **通信がRESTではない**：スキーマ定義を前提とする[gRPCとは？スタブ・チャネルの仕組みからREST APIとの違い](https://www.issoh.co.jp/column/details/3318/)で扱う構成では、.protoファイルが同じ役割を担います。OpenAPIを重ねる必要はありません。 - **検証目的の短命なプロトタイプ**：破棄が決まっている実装に定義ファイルを付けても、維持コストだけが残ります。 公開範囲や課金の設計まで含めて、自社APIを外部に出す判断そのものを検討している段階であれば、[API開発とは？自社APIを公開する目的・進め方・費用と外注判断](https://www.issoh.co.jp/column/details/16374/)で発注側の論点を整理しています。定義ファイルの設計から生成基盤の整備、既存システムとの接続までを含めて相談したい場合は、[API開発・システム連携](https://www.issoh.co.jp/service/system/api/)で当社の対応範囲を確認してください。 ## Swaggerの導入でつまずきやすい箇所と回避手順を実例で示す ### バージョン表記の混在で読み込みが止まる具体的な原因と回避手順 1つの案件に `swagger: "2.0"` の定義ファイルと `openapi: 3.0.3` の定義ファイルが混在する状態は、移行途中の現場でよく起きます。生成ツールは片方を読めても、もう片方で落ちます。回避手順は、移行対象を先に一覧化し、変換を一度で終わらせることです。混在期間を長く取るほど、生成設定の分岐が増えて戻せなくなります。 ### 本番環境でSwagger UIを公開したままにする危険と対策 Swagger UIは、エンドポイントの一覧と、リクエストを送る機能を同じ画面に載せます。検証環境の設定のまま本番へ出ると、内部向けのエンドポイントが一覧で読める状態になります。回避手順は、UIの配信をアプリケーションと分離し、社内ネットワークからのみ到達できる場所に置くことです。フレームワークがUIを自動で生やす構成では、その機能を環境変数で切り離します。FastAPIのように `/docs` を既定で公開する実装での閉じ方は、[FastAPIのSwagger UI（/docs）自動生成｜表示・カスタマイズ・本番で無効化する手順](https://www.issoh.co.jp/tech/details/2246/)に具体的な設定を載せています。 ### $refの相対パス解決がツール間で食い違う具体的な原因と回避策 定義ファイルを分割して `$ref: "./schemas/item.yaml"` のように参照すると、UIでは表示できるのに生成ツールでは解決できない、という食い違いが出ます。原因は、基準となるパスをどこに置くかの解釈差です。回避手順は2つあり、分割をやめて1ファイルに束ねるか、3.2.0の `$self` でベースURIを明示するかのどちらかです。分割の維持が要件でないなら、束ねるほうが事故は減ります。 ## よくある質問 ### SwaggerとOpenAPIは名称と仕様の関係でどう違うのですか？ 指すものが違います。OpenAPIはAPIの記述形式そのものの名前で、Swaggerはその形式を扱うツール群の名前です。2016年の改称以前は同じ名前で呼ばれていたため、古い記事では混在しています。判別は定義ファイルの1行目で行い、`openapi:` ならOpenAPI形式、`swagger:` なら改称前の形式です。 ### 定義ファイルはYAMLとJSONのどちらで書くべきか判断基準は何ですか どちらでも仕様上は同じです。人が編集する前提ならYAMLを選びます。コメントを書ける点と、階層が深くなっても行が短く収まる点が理由です。ツールが出力する側はJSONになる場面が多いため、両方が案件内に存在する状態は起こり得ます。編集する正本をYAMLに固定し、JSONは生成物として扱うと管理が単純になります。 ### Swagger UIを立てずに定義ファイルを確認する方法はありますか 画面なしでも確認できます。OpenAPI GeneratorのCLIイメージにある `validate` サブコマンドは、画面を立てずに仕様違反を検出します。Spectralを入れれば命名や説明文の欠落まで確認可能です。手元でざっと構造を見たいだけなら、この2つで足ります。UIが必要になるのは、実際にリクエストを送って応答を確かめたい段階からです。 ### 既存の3.0系定義ファイルを3.2.0へ上げる判断基準は何ですか 周辺ツールの対応が確認できるまでは急ぐ必要がありません。3.2.0は後方互換を保ったマイナーリリースで、既存の記述が無効になるわけではないためです。タグの階層化やSSEの表現といった追加要素を実際に使う予定があるかを先に確認し、使う予定がなければ据え置いて差し支えありません。 ### コード生成した成果物をリポジトリに含める実務上の判断基準は何ですか 受託開発では含める方針を推奨します。生成物が差分として見えるため、定義ファイルの変更がクライアント側にどう波及するかをレビューで確認できるからです。ただし手作業での編集は禁止し、CIの差分検知で編集を機械的に弾く設定を同時に入れてください。生成物を手で直す運用が始まると、定義ファイルが正本ではなくなります。 ## 関連記事 - [OpenAPIとは｜Swaggerとの違い・仕様書の書き方とSwagger UI](https://www.issoh.co.jp/tech/details/10408/)：本稿が前提にした仕様側の呼び名と記述方法を、用語の整理から解説しています - [FastAPIのSwagger UI（/docs）自動生成｜表示・カスタマイズ・本番で無効化する手順](https://www.issoh.co.jp/tech/details/2246/)：フレームワークが自動生成するUIの制御方法を、設定コード付きで扱っています - [JestとOpenAPIでAPIテストを自動化する方法](https://www.issoh.co.jp/tech/details/2273/)：定義ファイルをテストの入力に回す構成を、実装例で示しています - [API開発とは？自社APIを公開する目的・進め方・費用と外注判断](https://www.issoh.co.jp/column/details/16374/)：定義ファイルを整える前段にある、公開範囲と費用の判断を扱っています - [gRPCとは？スタブ・チャネルの仕組みからREST APIとの違いまで](https://www.issoh.co.jp/column/details/3318/)：OpenAPIを使わない選択肢として、スキーマ定義の別系統を説明しています --- 出典: [Swaggerとは：Editor・UIをDockerで動かす手順とOpenAPI 3.2対応の現況]()（株式会社一創）