RuoYi框架集成Swagger：从零构建优雅的API接口文档

1. 为什么需要Swagger接口文档在开发一个Web应用时前后端分离已经成为主流架构模式。后端负责提供API接口前端负责展示数据。但问题来了后端开发人员如何清晰地告诉前端每个接口的用途、参数和返回值传统做法是写Word文档或者Wiki但这种方式有几个明显的痛点首先文档更新不及时。后端代码改了但文档忘记更新导致前端调用出错。我就遇到过这种情况一个参数名从username改成了userName文档没同步更新前端同学调了半天才发现问题。其次文档格式不统一。不同开发人员写的文档风格各异有的详细有的简略新人接手项目时看得一头雾水。Swagger的出现完美解决了这些问题。它能自动从代码中提取接口信息生成统一的在线文档。最棒的是文档和代码永远保持同步再也不用担心文档过时的问题。在RuoYi框架中集成Swagger后前后端联调效率至少能提升50%。2. RuoYi项目初始化与Swagger集成2.1 创建RuoYi项目如果你还没有RuoYi项目可以从官网下载最新版本。我推荐使用RuoYi-Vue版本它前后端分离的架构更适合现代开发模式。下载解压后用IDEA打开项目确保能正常启动。这里有个小技巧第一次启动时建议先执行SQL脚本初始化数据库否则可能会遇到权限相关的问题。我就踩过这个坑启动时报了一堆权限错误排查了半天才发现是数据库没初始化。2.2 添加Swagger依赖RuoYi默认已经集成了Swagger但如果你想使用更强大的UI界面可以添加swagger-bootstrap-ui依赖。在pom.xml中加入dependency groupIdcom.github.xiaoymin/groupId artifactIdswagger-bootstrap-ui/artifactId version1.9.6/version /dependency这个版本是我在实际项目中使用过的稳定性很好。添加依赖后记得刷新Maven有时候IDEA不会自动加载新依赖我就遇到过明明加了依赖却找不到类的情况。2.3 修改Swagger访问路径默认的Swagger UI访问路径是/swagger-ui.html我们可以改成更简洁的/doc.html。全局搜索swagger-ui.html把所有出现的地方都替换成doc.html。在我的项目中需要修改两处Swagger配置类中的路径定义静态资源映射配置改完后访问http://localhost:8080/doc.html就能看到全新的UI界面了。这个界面比原生Swagger好看很多功能也更丰富。3. Swagger核心注解详解3.1 控制器层注解Api是Swagger最基础的注解用在Controller类上。我建议每个Controller都加上这个注解清楚地说明这个控制器是做什么的。例如Api(tags 用户管理模块) RestController RequestMapping(/system/user) public class UserController { // 方法实现 }ApiOperation用在具体的方法上描述接口功能。一个好的接口描述应该包含三要素做什么、需要什么参数、返回什么结果。例如ApiOperation(value 创建用户, notes 需要提供用户名、密码等基本信息) PostMapping public AjaxResult addUser(RequestBody User user) { // 实现代码 }3.2 参数描述注解ApiImplicitParams和ApiImplicitParam用来描述接口参数。这里最容易出错的是paramType它决定了参数放在请求的哪个位置queryGET请求的参数如/user?id123pathRESTful风格的路径参数如/user/123bodyPOST请求的JSON体form表单提交的参数一个完整的例子ApiOperation(分页查询用户列表) ApiImplicitParams({ ApiImplicitParam(name pageNum, value 页码, paramType query), ApiImplicitParam(name pageSize, value 每页数量, paramType query) }) GetMapping(/list) public TableDataInfo list(User user) { // 实现代码 }3.3 模型类注解ApiModel和ApiModelProperty用来描述数据模型。当接口使用RequestBody接收JSON参数时这些注解特别有用ApiModel(用户信息) public class User { ApiModelProperty(用户ID) private Long userId; ApiModelProperty(value 用户名, required true) private String userName; // getter/setter }注意required属性它标记了字段是否是必填项。这个信息对前端开发非常重要能减少很多不必要的沟通。4. 高级配置与最佳实践4.1 分组配置大型项目中接口可能非常多全部显示在一个页面会很混乱。Swagger支持分组显示不同模块的接口可以分开管理。在RuoYi中配置分组很简单Bean public Docket systemApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName(系统管理) .select() .apis(RequestHandlerPredicates.basePackage(com.ruoyi.system)) .build(); }我建议按照业务模块划分比如系统管理、订单管理、用户中心等每个模块一个分组。4.2 全局参数配置有些接口需要携带Token等全局参数我们可以统一配置避免每个接口都重复定义Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .globalOperationParameters(Collections.singletonList( new ParameterBuilder() .name(Authorization) .description(访问令牌) .modelRef(new ModelRef(string)) .parameterType(header) .required(true) .build())); }这样配置后所有接口都会自动带上Authorization头参数前端测试时就不需要每次都手动输入Token了。4.3 生产环境安全配置Swagger虽然方便但在生产环境直接暴露所有接口信息是有风险的。我建议做两件事通过profile控制Swagger的启用Profile({dev, test}) Configuration EnableSwagger2 public class SwaggerConfig { // 配置内容 }添加访问权限控制Bean public WebMvcConfigurer swaggerWebMvcConfigurer() { return new WebMvcConfigurer() { Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/doc.html) .addResourceLocations(classpath:/META-INF/resources/) .resourceChain(true) .addResolver(new PathResourceResolver() { Override protected Resource getResource(String resourcePath, Resource location) throws IOException { // 这里添加权限校验逻辑 return super.getResource(resourcePath, location); } }); } }; }5. 常见问题排查5.1 接口文档不显示如果配置了Swagger但访问/doc.html看不到接口首先检查控制器类是否有RestController或Controller注解方法是否有RequestMapping或GetMapping等映射注解包路径是否在Docket的扫描范围内我遇到过最奇葩的问题是Lombok导致的因为Swagger需要读取getter方法如果没正确安装Lombok插件会导致字段显示不出来。5.2 参数类型显示不正确有时候Swagger会把Integer参数显示成string这是因为没有正确指dataTypeApiImplicitParam(name age, value 年龄, dataType integer, paramType query)对于复杂对象确保使用了ApiModelProperty注解并且有正确的getter方法。5.3 文档界面加载缓慢如果文档界面加载很慢可能是网络问题导致Swagger的JS/CSS资源加载超时。可以考虑使用国内镜像源将静态资源打包到本地使用swagger-bootstrap-ui等替代方案我在一个内网项目中就遇到过这个问题最后是通过把资源文件放到本地解决的。