Springfox 解决在单一资源操作多个方法实现时生成 Swagger 文档

在命名本文的标题都敲打了几分钟时间，问题很简单，然而用简短的一个标题完全描述出来却有点费事。在 Spring MVC 项目结合 Springfox 来生成 Swagger API 文档时，如果一个资源操作因为请求参数的不同而映射到多个 controller 方法，那么 Swagger 可能只能生成某一个 API 条目，其余都被忽略。至于为什么说是 "可能",可能正好未遵循命名规范而躲过了这一劫。由此引出

我们的问题

我们这里用了资源操作一词，它包含了两部分信息: 资源与操作，比如/users/{userId}是资源，而发生在其上的 HTTP 各种方法，如 POST,GET,PUT,DELETE 等就是操作。而 Spring MVC 中允许我们针对不同的查询参数把相同的资源操作映射到不同的 controller 方法上，也是为了保持逻辑上更为清晰。

比如下面的例子路由配置的例子

GET /users/{userId} UserController.getUserInfo //默认
GET /users/{userId} UserController.getUserInfo //当有 ?source=file 时
GET /users/{userId} CloudUserController.getUserInfoFromCloud //当有 ?source=cloud 时

看到上面资源与操作完全相同，仅仅因为 source 查询参数的不同而映射到三个 controller 方法。用代码体现如下图阅读全文 >>