SpringBoot + Spring Security 项目集成 Swagger 3：轻松实现 API 文档与接口测试

前言

最近在写一个SpringBoot项目，在配置Swagger3的时候遇到了我没有想到的问题，本想休息一天，以为加个依赖配置一下就好，结果不知不觉搞了一天？！网上着了一堆博客材料根本运行不了一点，气得我配置成功后，当场写下这篇博客给大家做参考。

Swagger介绍

Swagger 3（OpenAPI 3.0）是一个广泛使用的 API 文档生成工具，能够自动化生成 API 接口文档，并提供交互式的 API 测试界面。它通过标准化的描述格式，帮助开发人员快速生成和维护 API 文档，支持请求参数、返回数据格式及 HTTP 状态码等信息的展示。Swagger UI 提供了一个可视化界面，用户可以直接在文档中测试 API 接口，验证其正确性。Swagger 3 还与多种工具兼容，有助于提高开发效率，并支持 API 版本管理，确保接口更新和版本控制更加清晰。

详细操作

首先我的springboot版本是2.7.16，swagger版本是1.8.0

一、添加swagger依赖

<!-- swagger3 -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.8.0</version>
        </dependency>

二、编写配置类

大家可以根据自己需求进行修改

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("swagger文档标题")
                        .description("swagger文档注释")
                        .version("1.0")
                        .termsOfService("服务地址"));
    }
}

三、SpringSecurity配置设置允许访问

根据网上的博客做下来一直运行不了可能就是这里url路径没有放开的问题，导致一直需要登录，无法显示界面

 @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
                //关闭csrf
                .csrf().disable()
                //不通过Session获取SecurityContext
                .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)
                .and()
                .authorizeRequests()

                //主要是这一句
                // 允许 Swagger 相关路径的匿名访问
                .antMatchers("/t","/swagger-ui/index.html", "/swagger-ui/**", "/swagger-resources/**", "/webjars/**", "/v3/api-docs/**").anonymous()
                // 对于登录接口 允许匿名访问
                .antMatchers("/user/login").anonymous()
                .antMatchers("/hello/**").hasRole("ADMIN")//对于/hello的路径，只有ADMIN权限的用户才能访问
                .antMatchers("/ok/**").hasAnyRole("ADMIN","TEACHER")//对于/ok的路径，ADMIN和USER权限的用户都可以访问
                // 除上面外的所有请求全部需要鉴权认证
                .anyRequest().authenticated();

        //添加自定义过滤器
        http.addFilterBefore(jwtAuthenticationTokenFilter, UsernamePasswordAuthenticationFilter.class);

        //添加自定义异常处理
        http.exceptionHandling().authenticationEntryPoint(authenticationEntryPoint).accessDeniedHandler(accessDeniedHandler);
    }

四、controller类加上Tag注解

@RestController
@RequestMapping("/user")
@Tag(name="用户管理",description = "用户登录登出")
public class UserController {
    @Autowired
    private LoginService loginService;

    @PostMapping("/login")
    public ResponseResult login(@RequestBody User user){
        return loginService.login(user);
    }

    @PostMapping("/logout")
    public ResponseResult logout(){
        return loginService.logout();
    }

}

运行项目后，如果报错的话就去application.properties中加上下面这一句

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

最后浏览器访问下面路径就行了，端口要记得改成自己的

http://localhost:8080/swagger-ui/index.html#/

访问成功的界面如下：

原文地址：https://blog.csdn.net/2301_77613763/article/details/143635138

免责声明：本站文章内容转载自网络资源，如本站内容侵犯了原著者的合法权益，可联系本站删除。更多内容请关注自学内容网（zxcms.com）！