はじめに
今回お話するのは「業務において知ったこと。」になります。
具体的には、「ローカル環境化でのSwagger」と「Github Pages Deployed Swagger」の違いを把握することができたので、こちらについて簡単な形にはなりますが、まとめさせていただきます。
※実際のSwaggerの設定方法については現段階で把握できていないので、説明はなしとさせていただきます。
対象者
- かけだしエンジニア
- ローカルと開発環境について理解が追い付いていない人
- Swaggerとは？の人
まずはSwaggerについて
Swaggerについての内容は下記記事を参考に
プラスαで下記内容もご参考までに
Swaggerとは
- APIの設計図＆説明書を作るための仕組み（正式には「OpenAPI Specification」）
- APIの仕様（URL・パラメータ・戻り値）を一目でわかる形で記述できる
- 「Swagger UI」を使うと、その仕様書を見やすくWeb表示＆ブラウザ上で試せるようになる
Swaggerを使用するメリット
- 見える化：APIのエンドポイントや使い方が一覧でわかる
- 試せる：ブラウザから直接APIリクエストを送って結果を確認できる（Postman不要な場合も）
- ドキュメント自動生成：ソースコードやアノテーションから仕様書を自動作成できる（例：Spring Boot, Rails）
- チーム共有が楽：同じ画面で開発者・テスター・デザイナーが仕様を確認できる
- 更新が容易：コード変更と連動させればドキュメントの更新漏れを防げる
他の便利な代替・補完ツール
Redoc。Stoplight Studio 。Postman。Insomnia。RapidAPI
本題：「ローカル環境化でのSwagger」と「Github Pages Deployed Swagger」の違い
経緯
- Githubからリポジトリをクローン。環境構築を完了。Java（Springフレームワーク）
- READMEの「Swagger（8080番号？）」と「Github Pages Deployed Swagger URL」の項目があり、Githubの方は閲覧可能だが、Swaggerの方は閲覧不可
-
docker coupose up -dのコマンドを実行した段階でローカルのSwaggerも閲覧できると思っていたけど、閲覧できない。。。なぜ？？？
↓ - ローカルSwaggerの閲覧（つまり開発段階の状態を確認したいなら）
./gradlew bootRunのコマンドを実行しないといけない
※Gradle（Javaのビルド＆実行ツール） でSpring Bootアプリを起動するコマンド
README記載の2つのSwaggerは何？？？
要点まとめ
- Swagger（ローカルや開発環境で起動する Swagger UI）
各自の開発マシンやローカルサーバー上で Swagger UI を動かし、http://localhost:xxxxx/swagger のような URL で API ドキュメントを確認できる。
開発中の API をすぐに可視化・テストできるツール - GitHub Pages にデプロイされた Swagger（静的ホスティング）
Swagger UI を GitHub Pages に配置すると、静的サイトとしてリポジトリから誰でもアクセス可能な URL（例：https://xn--wck1eucs30q.github.io/%E3%83%AA%E3%83%9D%E5%90%8D/swagger/）になる。
Git リポジトリに含まれる Swagger の定義（YAML や JSON）と UI ファイルを使って、Web 上にホスティングする構成
なぜ “2つの Swagger” が必要なのか？
- 開発（Swagger）
コード変更と同時に Swagger UI をローカルで表示し、動作確認。
高速で、外部に公開せず安全に作業できる。 - 共有・公開用（GitHub Pages）
他の開発者や関係者と API ドキュメントを簡単に共有できる。
GitHub 上でホスティングするため、サーバー構築不要で安価に公開できる。
URL が微妙に異なる理由
- ローカル版
例えば http://localhost:3000/swagger のように、開発マシン上のサーバーとポート番号が入っている。 - GitHub Pages 版
例えば https://username.github.io/repo-name/swagger/ のように、GitHub のドメインとリポジトリ名が含まれている。
↓
つまり、
・Swagger UI 自体は同じもの。
・「どこに置いてあるか」で見た目は変わらない。
・違いは “ローカルで開発用” と “ウェブ上で公開用” の使い分けにある、といえる。
さいごに
Laravelを使用した研修段階では、docker compose upと、場合によって？php artisan serveといったコマンドでローカルSwaggerの閲覧ができていました。
今回は初めてJava,Springの開発環境で事前にローカルSwaggerの確認手順を把握できていなくロスタイムが発生；；
言語のちがい（開発環境の違い？）でこういった違いがある事を知る事ができてよかったです。
おまけ（メモ）
- Dockerを止めたらローカルのSwaggerが見られなくなる？
Docker 上に Swagger UIを立ち上げて見ている状態＝Docker コンテナが動いているから見られている。
Docker を stop すると、そのコンテナは止まり、Swagger UI を提供するサーバーが動かなくなるため、ブラウザでも表示不可に。
- GitHub Pages の Swagger は Docker に関係なく見られるか？
関係なくみることができる。
GitHub Pages は「静的ウェブサイトをホスティングするサービス」で、Swagger UI に必要な HTML/CSS/JS ファイルと、Swagger の仕様書（YAMLやJSON）をリポジトリに置いておき、GitHub が自動で公開してくれる
- GitHub Pages の Swagger は「即時反映」される？
ローカルとは違って「即時反映」ではない。
ローカル環境で Swagger UI を立ち上げていた場合、ファイルを変更すれば、そのサーバーを再起動しなくてもすぐに反映されることが多い（ホットリロードなど）。
しかし GitHub Pages はリモート上のホスティングで、変更を反映させるには次のステップが必要になる- ローカルで変更内容を保存 → Git にコミット
- GitHub に push
- （必要なら）プルリクエスト → main（あるいは公開ブランチ）に merge
- GitHub Pages が更新され、新しい静的ファイルが公開される
おまけまとめ
- Docker を止めたらローカル Swagger は見られなくなる
- GitHub Pages の Swagger は Docker 不要でリモート公開される
- 即時反映されるのはローカルのみ。GitHub Pages はコミット → プッシュ → マージ → 自動デプロイが必要