結論：RedoclyでOpenAPI Specをタグで分割できる

Redocly CLIのfilter-in/filter-outデコレーターを使えば、1つのOpenAPI定義を複数のドキュメントに分割できる。

公開API用と管理API用でSwagger UIを分けたい場合など、タグベースでAPI仕様を分離できる。

背景：なぜ分割が必要か

単一のGo APIで複数のクライアント向けにエンドポイントを提供する場合、全エンドポイントを1つのSwagger UIに表示すると見づらい。

例：

  • 公開API: ユーザー機能、コンテンツ表示
  • 管理API: データ管理、レポート取得、設定変更

→ それぞれ専用のSwagger UIを生成したい

解決方法：Redocly CLI + filter デコレーター

1. swagでOpenAPI定義を生成

swag:
	@echo "==> Running swag init" >&2
	@swag init -g cmd/your-api/main.go -o docs
	@npx -y @redocly/cli@latest bundle docs/swagger.yaml --config docs/redocly-public.yaml -o docs/swagger_public.yaml
	@npx -y @redocly/cli@latest bundle docs/swagger.yaml --config docs/redocly-admin.yaml -o docs/swagger_admin.yaml && \
		sed -i -e 's,API for Public,API for Admin,g' docs/swagger_admin.yaml

2. 公開API用設定：管理タグを除外

docs/redocly-public.yaml:

decorators:
  filter-out:
    property: tags
    value: [admin]
    matchStrategy: any

filter-out: adminタグが付いたエンドポイントを除外 → 公開API向けのみ残る

3. 管理API用設定：管理タグのみ含める

docs/redocly-admin.yaml:

decorators:
  filter-in:
    property: tags
    value: [admin]
    matchStrategy: any

filter-in: adminタグが付いたエンドポイントのみ含める → 管理API向けのみ残る

デコレーターの動作

デコレーター動作用途
filter-in指定タグがあるエンドポイントのみ残す特定クライアント専用API
filter-out指定タグがないエンドポイントのみ残す特定クライアント向け除外

matchStrategy: any: 複数タグのいずれか1つでもマッチすればフィルタリング対象

Goコードでのタグ付け

// 公開APIエンドポイント（タグなし or public）
// @Tags user
// @Router /api/users [get]
func GetUsers(c *gin.Context) { ... }

// 管理APIエンドポイント（adminタグ）
// @Tags admin
// @Router /api/admin/reports [get]
func GetReports(c *gin.Context) { ... }

まとめ

  • Redocly CLIでOpenAPI Specをタグで分割できる
  • filter-in: 指定タグのみ含める
  • filter-out: 指定タグを除外
  • swag + Redoclyの組み合わせでクライアント別Swagger UIを生成
  • 1つのコードベースから複数のAPI仕様ドキュメントを管理可能