RuoYi-Vue后端接口文档：Swagger3.0配置教程
项目地址: https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue 你是否还在为后端接口调试繁琐而烦恼？是否希望拥有一份自动生成且美观易用的API文档？本文将详细介绍如何在RuoYi-Vue项目中配置Swagger3.0（OpenAPI 3.0），帮助你快速搭建专业的接口文档系统。读完本文后，你将能够：配置Swagger3.0环境、自定义API文档信息、设置接口安全认证、访问和使用接口文档。
Swagger3.0简介
Swagger（OpenAPI）是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。Swagger3.0（OAS 3.0）是其最新版本，相比之前版本有更简洁的规范和更强大的功能。在RuoYi-Vue项目中集成Swagger3.0，可以自动生成接口文档，方便前后端开发人员协作，减少接口文档维护成本。
配置文件解析
RuoYi-Vue项目的Swagger3.0配置主要集中在SwaggerConfig.java文件中，该文件位于ruoyi-framework/src/main/java/com/ruoyi/framework/config/目录下。
核心配置类
ruoyi-framework/src/main/java/com/ruoyi/framework/config/SwaggerConfig.java是Swagger3.0的核心配置类，下面对其关键代码进行解析：
@Configuration
public class SwaggerConfig {
/** 是否开启swagger */
@Value("${swagger.enabled}")
private boolean enabled;
/** 设置请求的统一前缀 */
@Value("${swagger.pathMapping}")
private String pathMapping;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30)
.enable(enabled)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build()
.securitySchemes(securitySchemes())
.securityContexts(securityContexts())
.pathMapping(pathMapping);
}
}
@Configuration：标识该类为配置类，会被Spring容器扫描并加载。@Value("${swagger.enabled}")：从配置文件中读取是否开启Swagger的配置，方便在不同环境（开发、测试、生产）中切换。Docket：Swagger的核心配置对象，DocumentationType.OAS_30指定使用Swagger3.0（OpenAPI 3.0）规范。enable(enabled)：根据配置决定是否启用Swagger。apiInfo()：配置API文档的基本信息，如标题、描述、版本等。select()：开始配置接口扫描策略。apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))：只扫描带有@ApiOperation注解的方法，这样可以精确控制哪些接口需要生成文档。paths(PathSelectors.any())：匹配所有路径。securitySchemes()和securityContexts()：配置接口安全认证相关信息，如Token认证。pathMapping(pathMapping)：设置请求的统一前缀。
API文档信息配置
apiInfo()方法用于配置API文档的基本信息，这些信息会显示在Swagger文档的首页。
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("标题：若依管理系统_接口文档")
.description("描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")
.contact(new Contact(ruoyiConfig.getName(), null, null))
.version("版本号:" + ruoyiConfig.getVersion())
.build();
}
title：文档标题。description：文档描述，简要说明接口文档的用途和涵盖的模块。contact：联系人信息，这里使用了系统配置的名称。version：文档版本号，与系统版本保持一致。
安全认证配置
为了保证接口的安全性，Swagger3.0支持配置认证方式，RuoYi-Vue项目中配置了基于Token的认证。
private List<SecurityScheme> securitySchemes() {
List<SecurityScheme> apiKeyList = new ArrayList<>();
apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));
return apiKeyList;
}
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(
SecurityContext.builder()
.securityReferences(defaultAuth())
.operationSelector(o -> o.requestMappingPattern().matches("/.*"))
.build());
return securityContexts;
}
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List<SecurityReference> securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
return securityReferences;
}
securitySchemes()：定义安全方案，这里配置了一个名为Authorization的API Key，位置在请求头中。securityContexts()：配置安全上下文，指定哪些路径需要应用安全方案。这里设置所有路径（/.*）都需要认证。defaultAuth()：定义默认的安全引用，指定授权范围。
资源映射配置
Swagger3.0的UI界面需要加载静态资源，RuoYi-Vue项目在ResourcesConfig.java中配置了资源映射。
ruoyi-framework/src/main/java/com/ruoyi/framework/config/ResourcesConfig.java
@Configuration
public class ResourcesConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
/** swagger配置 */
registry.addResourceHandler("/swagger-ui/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
}
}
addResourceHandler("/swagger-ui/**")：配置Swagger UI的访问路径。addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/")：指定Swagger UI静态资源的位置，这些资源通常由springfox-swagger-ui依赖提供。
安全配置放行
由于RuoYi-Vue项目集成了Spring Security，需要在安全配置中放行Swagger相关的URL，否则会被拦截。
ruoyi-framework/src/main/java/com/ruoyi/framework/config/SecurityConfig.java
@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http.authorizeRequests()
.antMatchers("/swagger-ui.html", "/swagger-resources/**", "/webjars/**", "/*/api-docs", "/druid/**").permitAll()
// 其他配置...
}
}
antMatchers("/swagger-ui.html", "/swagger-resources/**", "/webjars/**", "/*/api-docs", "/druid/**").permitAll()：允许所有用户访问Swagger相关的URL，包括UI页面、资源文件和API文档接口。
接口使用示例
RuoYi-Vue项目中提供了使用Swagger注解的示例，位于TestController.java中。
ruoyi-admin/src/main/java/com/ruoyi/web/controller/tool/TestController.java
@RestController
@RequestMapping("/test/swagger")
@Api(value = "Swagger测试接口", tags = {"Swagger测试接口"})
public class TestController {
@ApiOperation("获取列表")
@GetMapping("/list")
public AjaxResult list() {
List<String> list = new ArrayList<>();
list.add("swagger");
list.add("test");
return AjaxResult.success(list);
}
@ApiOperation("获取信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "int", paramType = "path")
@GetMapping("/info/{id}")
public AjaxResult info(@PathVariable("id") Integer id) {
return AjaxResult.success(id);
}
}
@Api：用在类上，描述类的作用。@ApiOperation：用在方法上，描述方法的作用。@ApiImplicitParam：描述方法的参数。
访问Swagger UI
完成上述配置后，启动项目，访问http://localhost:8080/swagger-ui/index.html即可打开Swagger3.0的UI界面。在界面上可以查看所有已配置的接口，测试接口调用，查看接口参数和返回值说明等。
总结
本文详细介绍了RuoYi-Vue项目中Swagger3.0的配置过程，包括核心配置类、API文档信息、安全认证、资源映射和安全放行等内容。通过集成Swagger3.0，可以大大提高前后端开发效率，减少接口文档维护成本。希望本文对你有所帮助，如果你有任何问题或建议，欢迎在评论区留言。
点赞、收藏、关注三连，获取更多RuoYi-Vue项目的实用教程！下期预告：RuoYi-Vue前端组件开发指南。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
