【ITニュース解説】How to Provide a Swagger UI Interface in Plain HTML That Works
2025年09月11日に「Dev.to」が公開したITニュース「How to Provide a Swagger UI Interface in Plain HTML That Works」について初心者にもわかりやすく解説しています。
ITニュース概要
Swagger UIは、APIドキュメントを簡単なHTMLとJavaScriptでインタラクティブに作成できる。CDN活用でサーバー不要、JSONやYAMLのAPI仕様から自動で分かりやすいUIが生成され、ブラウザ上でAPIの動作も試せる。初心者でもAPI連携がスムーズになり、効率的なドキュメント共有が可能だ。
ITニュース解説
システム開発において、プログラム同士が連携するための「窓口」となるAPI（Application Programming Interface）は欠かせない存在だ。しかし、APIを作るだけでは不十分で、そのAPIがどのように使われるべきかを示す「ドキュメント」も非常に重要となる。開発者自身がAPIを使う分には詳細なドキュメントは不要かもしれないが、他のチームや外部の協力会社、顧客がそのAPIを利用する場合には、正確で分かりやすいドキュメントが必須となる。
従来、APIの仕様はシンプルなテキストファイルで共有されることもあった。経験豊富な開発者にとってはそれでも事足りる場合があるが、利用者全員が経験豊富とは限らず、また、より洗練された方法が求められる場面も多い。APIの構成を共有するツールとしてはPostmanも広く利用されており、標準的な存在となりつつあるが、こちらは商用製品だ。
そこで注目されるのが、オープンソースのツールであるSwagger UIだ。Swagger UIは、APIの機能ドキュメントを提供するソリューションの一つで、その中でも特に人気が高い。OpenAPI Specification（OpenAPI仕様）という標準的な形式に基づいており、単なる読み物のドキュメントにとどまらない。なんと、Swagger UIを使うと、実際にAPIへのリクエストを試したり、それに対するサンプルレスポンスを確認したりできるのだ。これにより、APIの利用者は実際に手を動かしてAPIの動作を理解し、その場でテストまで行えるため、開発効率が飛躍的に向上する。
Swagger UIの大きな利点は、その導入の手軽さにある。一見すると、特別なサーバーや多くのリソースが必要そうに思えるが、実はそうではない。たった一枚のシンプルなHTMLファイルを作成するだけで、機能的なSwagger UIインターフェースを提供できるのだ。外部の依存関係をダウンロードして自身のサーバーでホストする必要すらなく、インターネット上に公開されているCDN（Contents Delivery Network）と呼ばれる「インターネット上のファイル倉庫」から必要なアセットを読み込むだけで簡単に実現できる。
具体的には、HTMLファイルに以下の2つのファイルを読み込むだけで始められる。一つはデザインを整えるためのCSSファイル、もう一つは機能を動かすためのJavaScriptファイルだ。これらのファイルは、cdnjsのような信頼性の高いCDNから直接読み込むことができるため、自身のサーバーにファイルを配置したり、サーバーサイドの特別なツールを用意したりする手間が一切かからない。
HTMLの <head> タグ内か、<body> タグの閉じタグの直前にこれらのファイルを記述する。
1<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.29.0/swagger-ui.min.css" crossorigin="anonymous" referrerpolicy="no-referrer"> 2<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.29.0/swagger-ui-bundle.min.js" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
次に、Swagger UIが表示される場所をHTML内に用意する。これは単なる div タグで十分だ。例えば、以下のように記述する。
1<div id="swagger-ui"></div>
この div タグの id 属性は任意だが、後述のJavaScriptコードでこの id を指定するため、両者で一致させる必要がある。
最後に、Swagger UIを初期化するためのJavaScriptコードを追加する。これにより、OpenAPI仕様のファイルを読み込み、それをインタラクティブなUIとして表示する。
1<script> 2 window.onload = () => { 3 window.ui = SwaggerUIBundle({ 4 url: 'https://petstore3.swagger.io/api/v3/openapi.json', // ここに自身のOpenAPI仕様ファイルのURLを指定 5 dom_id: '#swagger-ui', 6 }); 7 }; 8</script>
このJavaScriptコードでは、ページの読み込みが完了した際に SwaggerUIBundle を呼び出している。url プロパティには、APIの仕様が記述されたJSONまたはYAML形式のOpenAPI仕様ファイルのURLを指定する。ニュース記事の例では、公式のサンプルAPIのURLが使われているが、実際には自身のAPIの仕様ファイルを指すURLに置き換える必要がある。dom_id プロパティには、先ほどHTMLで用意した div タグのIDをCSSセレクタ形式で指定する。これにより、指定された div の中にSwagger UIが構築される。
このように手軽に導入できるSwagger UIだが、いくつか注意すべき点がある。特に重要なのが「CORS（Cross-Origin Resource Sharing）」の問題だ。CORSとは、ウェブブラウザがセキュリティのために、異なるドメイン（ウェブサイトのアドレス）にあるリソースへのアクセスを制限する仕組みのことだ。Swagger UIが表示されているウェブページとは異なるドメインにあるAPIを叩く場合、API側でCORSの設定が正しく行われていないと、Swagger UIからのリクエストがブロックされ、APIのテストができないという事態が発生する。APIの提供者は、Swagger UIからのアクセスを許可するようにAPIサーバーを設定する必要がある。
また、APIによっては認証が必要な場合がある。Swagger UIはOAuth 2.0のような標準的な認証プロトコルや、APIキーヘッダーを使った認証を標準でサポートしており、設定によってこれらを簡単に組み込むことができる。
Swagger UIそのものは、特別なサーバーを必要とせず、単一のHTMLファイルとして動作する。しかし、もちろん、ドキュメント化されているAPI自体は稼働しているサーバー上で提供されている必要がある。Swagger UIは、ブラウザの fetch() 関数を使ってAPIへのリクエストを行うため、APIがインターネット経由でアクセスできる状態になければ意味がない。
筆者は、より高度なカスタマイズや開発環境との連携のためにViteやRolldownといったツールを使いたいと考えているようだが、今回紹介されたシンプルなHTMLでの導入方法は、手軽にAPIドキュメントを提供したい場合に非常に効果的なアプローチだと言える。OpenAPI仕様のバージョンによってルーティングに関する問題に遭遇したという記述もあったが、これはOpenAPI仕様自体の理解に関わる問題であり、Swagger UIの機能とは直接関係ないとのことだ。
このように、Swagger UIはシステムエンジニアにとって、APIのドキュメンテーションとテストを効率的に行うための強力な味方となる。特に、シンプルなHTMLで手軽に導入できる点は、初心者がAPIの仕組みを理解し、実際に操作してみる上でも非常に価値のある方法だ。