ruoyi-vue-pro API文档：Swagger自动生成与定制化-优快云博客

ruoyi-vue-pro API文档：Swagger自动生成与定制化

【免费下载链接】ruoyi-vue-pro 🔥 官方推荐 🔥 RuoYi-Vue 全新 Pro 版本，优化重构所有功能。基于 Spring Boot + MyBatis Plus + Vue & Element 实现的后台管理系统 + 微信小程序，支持 RBAC 动态权限、数据权限、SaaS 多租户、Flowable 工作流、三方登录、支付、短信、商城、CRM、ERP、AI 大模型等功能。你的 ⭐️ Star ⭐️，是作者生发的动力！项目地址: https://gitcode.com/GitHub_Trending/ruoy/ruoyi-vue-pro

概述

在现代Web应用开发中，API文档的维护一直是个痛点。传统的手动编写文档方式不仅效率低下，还容易出现文档与实际代码不一致的问题。ruoyi-vue-pro项目基于Springdoc OpenAPI + Knife4j技术栈，实现了API文档的自动生成与高度定制化，为开发者提供了完整的API文档解决方案。

技术架构

ruoyi-vue-pro采用Spring Boot + Springdoc OpenAPI + Knife4j的技术组合：

mermaid

核心组件说明

组件	版本	功能描述
Springdoc OpenAPI	1.7.0	基于OpenAPI 3.0规范的Spring Boot集成
Knife4j	4.1.0+	增强的Swagger UI界面，提供更好的用户体验
OpenAPI	3.0	行业标准的API描述规范

快速开始

1. 依赖配置

ruoyi-vue-pro已在yudao-spring-boot-starter-web模块中集成了Swagger功能，无需额外配置依赖。

2. 基础配置

项目通过SwaggerProperties配置类管理Swagger相关配置：

@ConfigurationProperties("yudao.swagger")
@Data
public class SwaggerProperties {
    private String title;          // 文档标题
    private String description;    // 文档描述
    private String author;         // 作者信息
    private String version;        // API版本
    private String url;            // 项目URL
    private String email;          // 联系邮箱
    private String license;        // 许可证
    private String licenseUrl;     // 许可证URL
}

3. 自动配置

YudaoSwaggerAutoConfiguration类负责自动配置：

@AutoConfiguration
@ConditionalOnClass({OpenAPI.class})
@EnableConfigurationProperties(SwaggerProperties.class)
@ConditionalOnProperty(prefix = "springdoc.api-docs", name = "enabled", 
                       havingValue = "true", matchIfMissing = true)
public class YudaoSwaggerAutoConfiguration {
    
    @Bean
    public OpenAPI createApi(SwaggerProperties properties) {
        // 创建OpenAPI配置
        return new OpenAPI()
            .info(buildInfo(properties))
            .components(new Components().securitySchemes(securitySchemas))
            .addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION));
    }
}

API注解使用指南

控制器级别注解

@Tag(name = "管理后台 - 部门")
@RestController
@RequestMapping("/system/dept")
public class DeptController {
    // 控制器方法
}

方法级别注解

@PostMapping("create")
@Operation(summary = "创建部门")
@PreAuthorize("@ss.hasPermission('system:dept:create')")
public CommonResult<Long> createDept(@Valid @RequestBody DeptSaveReqVO createReqVO) {
    // 业务逻辑
}

参数级别注解

@DeleteMapping("delete")
@Operation(summary = "删除部门")
@Parameter(name = "id", description = "编号", required = true, example = "1024")
public CommonResult<Boolean> deleteDept(@RequestParam("id") Long id) {
    // 业务逻辑
}

高级定制功能

1. 多租户支持

ruoyi-vue-pro自动为所有API添加租户编号参数：

private static Parameter buildTenantHeaderParameter() {
    return new Parameter()
        .name(HEADER_TENANT_ID)
        .description("租户编号")
        .in(String.valueOf(SecurityScheme.In.HEADER))
        .schema(new IntegerSchema()._default(1L));
}

2. 安全认证

自动配置JWT Token认证参数：

private static Parameter buildSecurityHeaderParameter() {
    return new Parameter()
        .name(HttpHeaders.AUTHORIZATION)
        .description("认证Token")
        .in(String.valueOf(SecurityScheme.In.HEADER))
        .schema(new StringSchema()._default("Bearer test1"));
}

3. API分组

支持按模块进行API分组：

@Bean
public GroupedOpenApi allGroupedOpenApi() {
    return GroupedOpenApi.builder()
        .group("all")
        .pathsToMatch("/admin-api/**", "/app-api/**")
        .build();
}

Knife4j增强功能

1. 界面优化

Knife4j提供了比原生Swagger UI更友好的界面：

中文界面支持
离线文档导出
接口调试功能
动态参数示例

2. 扩展属性

支持自定义扩展属性：

private void addOrderExtension(OpenAPI openApi) {
    // 为tags添加x-order排序属性
    openApi.getTags().forEach(tag -> {
        tag.addExtension(ExtensionsConstants.EXTENSION_ORDER, orderValue);
    });
}

配置示例

application.yml配置

yudao:
  swagger:
    title: RuoYi-Vue-Pro API文档
    description: 基于Spring Boot + Vue的前后端分离权限管理系统
    author: 芋道源码
    version: 1.0.0
    url: https://gitee.com/zhijiantianya/ruoyi-vue-pro
    email: 469901269@qq.com
    license: MIT
    license-url: https://mit-license.org/

springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
    enabled: true

knife4j:
  enable: true
  setting:
    language: zh_cn

最佳实践

1. 统一的响应格式

所有API使用统一的响应格式：

public class CommonResult<T> implements Serializable {
    private Integer code;    // 状态码
    private T data;         // 返回数据
    private String msg;     // 提示信息
}

2. 完整的注解文档

为每个API方法提供完整的注解信息：

@GetMapping("/list")
@Operation(summary = "获取部门列表", 
           description = "用于部门管理界面展示部门树形结构")
@Parameters({
    @Parameter(name = "name", description = "部门名称", example = "研发部"),
    @Parameter(name = "status", description = "状态", example = "1")
})
public CommonResult<List<DeptRespVO>> getDeptList(DeptListReqVO reqVO) {
    // 业务逻辑
}

3. 权限控制集成

与Spring Security权限控制无缝集成：

@PostMapping("create")
@Operation(summary = "创建部门")
@PreAuthorize("@ss.hasPermission('system:dept:create')")
public CommonResult<Long> createDept(@Valid @RequestBody DeptSaveReqVO createReqVO) {
    // 需要system:dept:create权限才能访问
}

常见问题解决

1. 文档不显示问题

如果Swagger文档无法访问，检查以下配置：

springdoc.api-docs.enabled=true
确保没有安全拦截器阻止访问
检查Knife4j是否启用

2. 注解不生效问题

确保控制器类被正确扫描：

控制器类添加@RestController注解
包路径在Spring Boot扫描范围内

3. 生产环境禁用

生产环境建议禁用Swagger：

springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

性能优化建议

1. 按需加载

在开发环境启用，生产环境禁用：

@ConditionalOnProperty(prefix = "springdoc.api-docs", 
                       name = "enabled", 
                       havingValue = "true")

2. 分组加载

按业务模块分组加载API文档，减少单次加载量。

3. 缓存策略

合理配置缓存策略，避免重复生成文档。

总结

ruoyi-vue-pro通过Springdoc OpenAPI + Knife4j的组合，提供了完整的API文档自动化解决方案。主要优势包括：

自动化生成：基于代码注解自动生成API文档
实时同步：文档与代码保持实时一致
高度定制：支持丰富的定制化配置
多租户支持：内置多租户API参数支持
安全集成：与权限控制系统无缝集成
友好界面：Knife4j提供更好的用户体验

通过合理使用Swagger注解和配置，可以大幅提升API文档的维护效率和质量，为前后端协作提供强有力的支持。

温馨提示：本文档基于ruoyi-vue-pro项目实际代码分析编写，所有代码示例均来自项目源码。建议在实际使用时参考项目的最新版本和文档。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考