将Swagger接口合并到Controller中是否属于合理的开发实践？

这个方案是目前行业内非常常见的选型，没有绝对的好坏，完全取决于团队的实际业务场景和开发规范，具体的利弊和适用场景如下：

该方案的优势 #

• 降低维护同步成本：接口逻辑和Swagger描述存放在同一个文件中，开发修改接口逻辑时可以同步调整注解说明，不会出现接口迭代后独立Swagger文件忘了更新的文档不一致问题
• 降低开发理解成本：排查接口问题、核对参数规则时，不需要在Controller和独立Swagger文件之间来回跳转，单个文件就能拿到完整的接口信息
• 减少冗余结构：不需要额外维护独立的Swagger接口类/配置层，减少项目中不必要的层级，也不需要处理独立Swagger文件和Controller的映射关系，避免映射错误导致的文档缺失问题
• 上手门槛低：新接触项目的开发不需要额外学习独立Swagger文件的编写规范，只要会用基础Swagger注解就能直接维护文档

该方案的弊端 #

• 会导致Controller代码冗余：如果接口参数、返回值的说明比较复杂，大量@Api、@ApiOperation、@ApiImplicitParam类注解会占据大量代码行数，让Controller的核心业务逻辑被淹没在注解中，降低业务代码的可读性
• 工具耦合性高：Swagger属于文档类工具依赖，将注解直接写在业务代码中，相当于把工具依赖耦合到了业务层，如果后续要替换接口文档工具（比如换成SpringDoc、停用自动文档生成），需要修改所有Controller的代码，改造成本很高
• 多场景适配不灵活：如果同一套Controller需要对外输出多套不同的接口文档（比如对内完整版和对外精简版的字段说明、接口展示范围不同），直接写在Controller里的注解没法灵活切换配置，只能硬编码判断，实现成本极高
• 非开发人员无法独立维护：如果是产品、测试人员需要调整接口说明，看不懂Java代码的情况下没法直接修改，必须要开发人员协助调整，文档维护效率更低

选型建议 #

如果你的团队符合以下场景可以直接采用该方案：

• 项目规模不大，Controller逻辑本身比较精简，注解增加的代码量不会造成太大的阅读负担
• 没有多版本接口文档输出的需求，文档内容和接口逻辑强绑定，不需要单独维护文档内容
• 团队有明确的编码规范，要求接口修改时必须同步调整注解说明
  如果团队有复杂文档维护需求、或者不想让工具依赖侵入业务代码，可以折中采用提取公共接口层+注解写在接口层的方案，Controller实现对应的公共接口，既保留了接口和文档绑定的优势，也避免了Swagger注解侵入业务实现代码。

内容的提问来源于stack exchange，提问作者user1354825