// the find
dyc87112/swagger-butler
API文档管家 - 基于Swagger与Zuul实现的API文档聚合工具
Swagger Butler is a Spring Boot module that sits behind a Zuul gateway and merges the Swagger 2.0 docs of each routed service into one Swagger UI page, so developers stop hunting for per-service doc URLs. It targets teams running Spring Boot 1.x or 2.x services behind Zuul, with or without Eureka or Consul discovery.
- The Zuul route table is the source of truth. With swagger.butler.auto-generate-from-zuul-routes=true, every route becomes a doc source, so there is no separate index to maintain. Adding a service means adding a route, which you already had to do.
- Discovery support is thin. The Eureka and Consul examples add the discovery starter and @EnableDiscoveryClient, and Zuul's auto-created service routes feed the same generator, so the aggregation code does not need to know which registry is in use.
- Per-resource overrides for api-docs-path and swagger-version cover services with a context-path or a custom doc path without forking the aggregation logic.
- The core module is five classes (an enable annotation, auto-config, two properties classes, and a resources processor), so it is easy to read and debug when the aggregated list is wrong.
- It is built on Zuul 1. Spring Cloud has moved off Netflix Zuul toward Spring Cloud Gateway, so starting a new gateway on this stack means adopting a dead end. The README lists only Spring Boot 1.x and 2.x and says nothing about a Spring Boot 3 path.
- The last push was 2024-08-26, and the README still uses Spring Cloud 2.0.0.RELEASE. Nothing I was given shows activity since then, so treat this as a reference implementation rather than something to depend on without checking the issue tracker first.
- The README documents only Swagger 2.0 and /v2/api-docs. Services on OpenAPI 3 (springdoc, /v3/api-docs) are not covered, and the README does not say whether the aggregated UI can render those specs.
- All documentation traffic goes through the gateway, so a service's docs are reachable only if its route is, and the README says nothing about authentication for the aggregated page or the downstream doc endpoints. That matters if the gateway is exposed publicly.