Swagger UI スキル

概要

Swagger UI、ReDoc、その他のインタラクティブ API ドキュメントツールの設定と統合に関する専門知識を提供します。

コマンドリファレンス

# リソース参照
cat .claude/skills/swagger-ui/resources/swagger-ui-configuration.md
cat .claude/skills/swagger-ui/resources/redoc-configuration.md
cat .claude/skills/swagger-ui/resources/cicd-integration.md

# テンプレート参照
cat .claude/skills/swagger-ui/templates/swagger-ui-nextjs.tsx
cat .claude/skills/swagger-ui/templates/swagger-config.json

知識領域 1: ツール選択

Swagger UI vs ReDoc

選択基準

• Swagger UI: 開発者が直接 API をテストする必要がある場合
• ReDoc: 外部公開ドキュメントで可読性を重視する場合
• 両方: 開発環境は Swagger UI、本番環境は ReDoc

知識領域 2: Swagger UI 設定

基本設定オプション

docExpansion オプション

認証プリセット

開発環境での認証情報プリセット:

const ui = SwaggerUIBundle({
  url: "/openapi.yaml",
  requestInterceptor: (req) => {
    req.headers["Authorization"] = "Bearer dev-token";
    return req;
  },
  persistAuthorization: true,
});

知識領域 3: ReDoc 設定

基本設定オプション

テーマカスタマイズ

<redoc
  spec-url="/openapi.yaml"
  theme='{
    "colors": {
      "primary": { "main": "#32329f" }
    },
    "typography": {
      "fontSize": "14px",
      "fontFamily": "system-ui"
    },
    "sidebar": {
      "width": "260px"
    }
  }'
></redoc>

知識領域 4: フレームワーク統合

Next.js App Router 統合

// app/api-docs/page.tsx
"use client";

import dynamic from "next/dynamic";

const SwaggerUI = dynamic(() => import("swagger-ui-react"), {
  ssr: false,
  loading: () => <p>Loading API Documentation...</p>,
});

export default function ApiDocs() {
  return <SwaggerUI url="/openapi.yaml" />;
}

Express 統合

import swaggerUi from "swagger-ui-express";
import YAML from "yamljs";

const swaggerDocument = YAML.load("./openapi.yaml");

app.use(
  "/api-docs",
  swaggerUi.serve,
  swaggerUi.setup(swaggerDocument, {
    customCss: ".swagger-ui .topbar { display: none }",
    customSiteTitle: "API Documentation",
  }),
);

知識領域 5: カスタマイズ

CSS カスタマイズ

/* Swagger UIトップバー非表示 */
.swagger-ui .topbar {
  display: none;
}

/* カスタムカラー */
.swagger-ui .info .title {
  color: #32329f;
}

/* フォントカスタマイズ */
.swagger-ui {
  font-family: "Inter", system-ui, sans-serif;
}

/* レスポンシブ対応 */
@media (max-width: 768px) {
  .swagger-ui .opblock-section-header {
    flex-direction: column;
  }
}

ブランディング

知識領域 6: セキュリティ考慮

本番環境での注意点

Try it out 無効化

SwaggerUIBundle({
  url: "/openapi.yaml",
  supportedSubmitMethods: [], // すべてのメソッドで無効化
});

判断基準チェックリスト

設定品質

• OpenAPI 仕様ファイルが正しく読み込まれるか？
• Try it out 機能が動作するか？（Swagger UI）
• 認証設定が適切か？

カスタマイズ品質

• ブランディングが適用されているか？
• モバイルでも適切に表示されるか？
• パフォーマンスに問題がないか？

セキュリティ品質

• 本番環境で機密情報が露出していないか？
• 適切なアクセス制限がかかっているか？

関連スキル

• .claude/skills/openapi-specification/SKILL.md: OpenAPI 仕様書作成
• .claude/skills/api-versioning/SKILL.md: バージョニング戦略
• .claude/skills/ci-cd-pipelines/SKILL.md: CI/CD 統合

変更履歴