Docker ComposeでSwagger UIをデプロイ：複数API管理の効率化

現代のマイクロサービスアーキテクチャでは、APIドキュメントツールの展開は、複雑な認証設定、複数バージョンAPIドキュメントの共存、開発環境と本番環境の乖離という課題に直面しがちです。本稿では、Docker Composeを利用してSwagger UIをコンテナ化し、環境変数による設定、Nginxリバースプロキシ、複数サービス連携を含む包括的なソリューションを提供します。これにより、わずか15分でスケーラブルなAPIドキュメントサービスを構築する手順を詳述します。

コンテナベースのアーキテクチャ設計

Swagger UIのDockerデプロイメントは、三層構造に基づいています。基盤層は公式のNginxイメージをWebサービスとして利用し、設定層は環境変数を介して動的なパラメータ調整を可能にします。アプリケーション層では、Swagger UIのリソース読み込みとAPIドキュメントのレンダリングを担当します。主要な設定ファイルはdocker/default.conf.templateにあり、Nginxのgzip圧縮およびCORSポリシーにより、フロントエンドリソースのロード性能が最適化されています。

このアーキテクチャの利点は以下の通りです。

環境の一貫性: Dockerコンテナにより、開発、テスト、本番環境間での一貫性が保証されます。
動的な設定: docker/configurator/index.jsを活用し、環境変数からフロントエンド設定への自動変換を実現します。
サービス統合: 複数のマイクロサービスのOpenAPI仕様ファイルを同時にロードすることが可能です。

基本的なデプロイ手順

1. 環境準備

ローカル環境にDockerとDocker Composeがインストールされていることを確認してください。次に、プロジェクトリポジトリをクローンします。

git clone https://gitcode.com/gh_mirrors/swa/swagger-ui
cd swagger-ui

2. 単一サービスでの迅速な起動

プロジェクトに組み込まれたDockerfileを使用して、ベースサービスをビルドし起動します。

docker build -t api-doc-ui-image .
docker run -p 9000:80 -e API_SPEC_URL=http://localhost:8081/openapi.yaml api-doc-ui-image

このコマンドは、環境変数API_SPEC_URLを介してAPIドキュメントのアドレスを指定します。コンテナの起動時に、docker/docker-entrypoint.d/40-swagger-ui.shスクリプトが自動的に実行され、設定の注入とNginxの起動が行われます。

Docker Composeによる複数サービス設定

docker-compose.ymlの記述

Swagger UIと二つのAPIサービスを含むdocker-compose.ymlを作成します。

version: '3.8'
services:
  api-documentation-ui:
    build: .
    ports:
      - "9000:80"
    environment:
      - APP_ROOT=/api-docs
      - OPENAPI_SPEC_PATHS=/openapi/backend-a.yaml,/openapi/backend-b.yaml
    volumes:
      - ./api_definitions:/usr/share/nginx/html/openapi
    depends_on:
      - backend-a
      - backend-b

  backend-a:
    image: nginx:alpine
    volumes:
      - ./backend-a-spec.yaml:/usr/share/nginx/html/openapi/backend-a.yaml
    ports:
      - "9001:80"

  backend-b:
    image: nginx:alpine
    volumes:
      - ./backend-b-spec.yaml:/usr/share/nginx/html/openapi/backend-b.yaml
    ports:
      - "9002:80"

複数ドキュメントの読み込み設定

OPENAPI_SPEC_PATHS環境変数にカンマ区切りで複数のドキュメントアドレスを指定することで、複数ドキュメントの読み込みをサポートします。コンテナ起動時にdocker/configurator/index.jsがこれらのパスを自動的に解析し、対応するフロントエンド設定を生成します。これは、以下のJavaScriptスニペットが示すように、環境変数を設定に変換する役割を担っています。

window.ui = SwaggerUIBundle({
  ${indent(translator(process.env, {injectBaseConfig: true}), 8, 2)}
});

上記のコードは、translator関数がprocess.envを通じて取得した環境変数をSwagger UIの設定オブジェクトに変換し、それをSwaggerUIBundleの初期化時に注入することで、動的な設定を可能にしています。

高度な設定テクニック

1. 認証機能の統合

APIドキュメントを保護するため、Nginx設定にHTTP Basic認証を追加できます。

location /api-docs {
  auth_basic "APIドキュメント認証";
  auth_basic_user_file /etc/nginx/.htpasswd;
  # その他の設定...
}

2. カスタムテーマの適用

カスタムCSSファイルをマウントして、デフォルトのスタイルを上書きすることが可能です。

volumes:
  - ./theme/custom_styles.css:/usr/share/nginx/html/styles/custom.css
environment:
  - UI_CUSTOM_STYLESHEET=styles/custom.css

3. 開発環境でのホットリロード

docs/samples/webpack-getting-started/webpack.config.jsを参考に、Webpackを使用して開発環境でホットリロードを実現できます。

module.exports = {
  mode: 'development',
  devServer: {
    static: './build',
    hot: true,
    proxy: {
      '/api/v1': 'http://localhost:8000'
    }
  },
  // その他の設定...
};

一般的な問題とその解決策

1. CORSクロスオリジン問題

Swagger UIがリモートのAPIドキュメントを読み込む際にCORSエラーが発生した場合、Nginx設定を変更してCORSを有効にする必要があります。docker/default.conf.templateに以下のヘッダを追加してください。

add_header Access-Control-Allow-Origin *;
add_header Access-Control-Allow-Methods GET,POST,OPTIONS;
add_header Access-Control-Allow-Headers Content-Type,Authorization;

2. 大規模ドキュメントの読み込み最適化

5MBを超えるOpenAPIドキュメントの場合、以下の対策が推奨されます。

Nginxのgzip圧縮を有効にする（デフォルト設定で有効）。
docExpansion: "none"を設定し、すべてのAPIノードをデフォルトで折りたたむ。
ドキュメントを複数の小さな仕様ファイルに分割することを検討する。

デプロイのベストプラクティス

本番環境設定チェックリスト

設定項目	推奨値	設定ファイルの場所
コンテナリソース制限	cpu: 1.0, memory: 1024M	docker-compose.yml
ヘルスチェック	`curl -f http://localhost:9000/api-docs`
ログドライバ	json-file, ファイルサイズ制限	docker-compose.yml
HTTPS設定	Certbotによる証明書自動生成	Nginx設定ファイル

CI/CD統合の推奨事項

Swagger UIのデプロイをCI/CDワークフローに組み込むには、以下の点を考慮してください。

コードコミット時にOpenAPI仕様の有効性を自動で検証する。
ビルドステージで最新のSwagger UIイメージを生成し、プライベートレジストリにプッシュする。
Docker Composeの--env-fileパラメータを使用して、環境ごとの設定を区別する。
デプロイ後にヘルスチェックを実行し、サービスの可用性を確認する。

まとめと今後の展望

本稿で紹介したDocker Composeデプロイメント戦略は、多くのチームのAPIドキュメント要件をカバーします。さらに高度な利用として、OAuth2認証を統合してドキュメントアクセス権限を制御したり、docs/customization/add-plugin.mdを参考にカスタムプラグインを開発してSwagger UIの機能を拡張したりすることが考えられます。また、ELKスタックと連携してAPI呼び出しログを分析したり、Kubernetesを導入して高可用性デプロイを実現したりする方向性もあります。

プロジェクトの公式ドキュメントdocs/usage/installation.mdには、さらに多くのデプロイオプションと設定パラメータが記載されており、実際の要件に合わせて最適化を進めることをお勧めします。コンテナ化されたデプロイメントを通じて、チームはドキュメントツールのメンテナンスではなく、API設計そのものにより多くの労力を集中できるようになるでしょう。

タグ: SwaggerUI DockerCompose nginx OpenAPI Microservices

6月18日 21:22 投稿

異端開発室