快速体验
- 打开 InsCode(快马)平台 https://www.inscode.net
- 输入框内输入如下内容：
开发一个多模块企业级API系统，要求：1. 按业务模块分组展示Swagger路径（用户中心、订单中心、支付中心）2. 实现基于JWT的Swagger访问权限控制 3. 支持API版本管理（v1/v2路径）4. 自动生成离线API文档（PDF格式）5. 集成API调用监控功能- 点击'项目生成'按钮，等待项目生成完整后预览效果
在企业级API开发中，Swagger作为接口文档工具的重要性不言而喻。但实际落地时，很多团队都会遇到访问路径混乱、权限管控缺失等问题。最近我在一个电商系统重构项目中，就遇到了这样的挑战。经过实践，总结出一套Swagger路径管理的最佳实践方案，分享给大家。
- 业务模块分组展示电商系统通常包含用户中心、订单中心、支付中心等多个模块。如果所有接口都混在一起展示，开发和测试效率会大打折扣。我们通过Swagger的Group功能实现了模块化展示：
- 为每个业务模块创建独立的Docket配置
- 使用@Bean注解注册不同模块的分组
通过paths()方法限定各模块只扫描对应包路径 这样访问/swagger-ui.html时，右上角就会出现模块切换下拉框，开发人员可以快速定位到目标接口。
JWT权限控制生产环境直接暴露Swagger存在安全隐患。我们实现了基于JWT的访问控制：
- 在Swagger配置类中添加全局Authorization头参数
- 自定义拦截器校验JWT令牌有效性
通过@PreAuthorize注解控制不同角色的访问权限 管理员可以看到所有模块，普通开发只能访问指定模块，未登录用户直接跳转登录页。
API版本管理随着业务迭代，接口版本管理必不可少。我们采用路径版本号方案：
- 在@RequestMapping中统一添加/v1/、/v2/前缀
- 配置多个Docket分别扫描不同版本路径
使用@ApiVersion注解标记接口版本 这样既保持了接口兼容性，又能清晰展示各版本差异。测试时可以通过切换分组对比不同版本接口。
离线文档生成客户经常需要离线API文档。我们通过maven插件实现了自动化：
- 配置swagger2markup插件转换JSON为AsciiDoc
- 使用asciidoctor插件生成PDF文档
在CI/CD流程中添加文档生成任务 每次发版都会自动生成带版本号的PDF文档，省去了手动维护的麻烦。
调用监控集成为了掌握接口使用情况，我们扩展了Swagger的统计功能：
- 通过Filter记录每个Swagger页面的访问日志
- 集成Prometheus监控接口调用频次
- 开发看板展示热门接口排行 这些数据帮助我们发现，支付模块的文档查看频率是其他模块的3倍，于是优先优化了该模块的文档示例。
在整个实践过程中，InsCode(快马)平台的一键部署功能帮了大忙。不需要手动配置复杂的Swagger环境，导入项目后就能立即看到效果，调试权限控制逻辑时特别高效。
这套方案实施后，新入职开发人员接入效率提升了60%，接口变更导致的沟通成本降低了45%。建议大家在设计Swagger路径时，提前考虑好权限、版本、监控等企业级需求，避免后期重构。
快速体验
- 打开 InsCode(快马)平台 https://www.inscode.net
- 输入框内输入如下内容：
开发一个多模块企业级API系统，要求：1. 按业务模块分组展示Swagger路径（用户中心、订单中心、支付中心）2. 实现基于JWT的Swagger访问权限控制 3. 支持API版本管理（v1/v2路径）4. 自动生成离线API文档（PDF格式）5. 集成API调用监控功能- 点击'项目生成'按钮，等待项目生成完整后预览效果
