SpringBoot集成swagger和jwt

java_学习爱好者

已于 2025-04-04 00:41:52 修改

阅读量855

点赞数 11

CC 4.0 BY-SA版权

文章标签： java 开发语言

于 2025-04-04 00:26:32 首次发布

本文链接：https://blog.youkuaiyun.com/weixin_65019617/article/details/146991174

一、集成swagger文档

1.简介

2.OpenAPI3集成swagger文档

3.springfox集成swagger

二、集成JWT

一、集成swagger文档

为了方便后端人员进行进行接口测试，swagger就此诞生

1.简介

API 文档自动生成

减少文档编写工作：通过在代码中使用注解，Swagger 可以自动生成详细的 API 文档，减少了手动编写文档的工作量。
保持文档与代码同步：由于文档是直接从代码生成的，因此可以确保文档总是与实际的 API 实现保持一致。

交互式 API 测试

实时测试 API：Swagger UI 提供了一个基于浏览器的界面，允许开发者直接从浏览器调用 API 并查看响应结果，这有助于快速测试 API 功能。
参数输入与验证：用户可以直接在界面上输入参数并发送请求，Swagger 会自动处理参数格式和验证。

API 设计和开发协作

统一的 API 规范：Swagger 使用 OpenAPI 规范（以前称为 Swagger 规范），这是一种标准的 API 描述格式，使得团队成员可以更容易理解和遵循 API 设计。
前后端分离开发：前端和后端开发者可以通过 Swagger 文档进行沟通，即使在后端 API 还未完成时，前端也可以开始基于文档进行开发。

2.OpenAPI3集成swagger文档

OpenAPI 3 是最新的swagger文档标准，它提供了更好的功能和支持。此外，OpenAPI 3 增加了许多新特性，如改进的安全性描述、回调定义等，这些都是旧版本所不具备的。SpringBoot3项目推荐使用此版本。

导入依赖

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>4.3.0</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>2.15.2</version> 
        </dependency>

文档配置

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;


@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                // 接口文档标题
                .info(new Info().title("在线考试系统API接口文档")
                        // 接口文档简介
                        .description("这是基于Knife4j OpenApi3的在线考试系统接口文档")
                        // 接口文档版本
                        .version("v1.0")
                        // 开发者联系方式
                        .contact(new Contact().name("黄宏保").email("3111871135@qq.com")))
                .externalDocs(new ExternalDocumentation()
                        .description("在线考试系统接口文档")//swagger-ui文档地址
                        .url("http://127.0.0.1:8088"));
    }

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder().group("管理员管理模块")
                .pathsToMatch("/user/**","/admin/**")
                .build();
    }

    @Bean
    public GroupedOpenApi teacherApi() {
        return GroupedOpenApi.builder().group("教师管理模块")
                .pathsToMatch("/user/**", "/teacher/**")
                .build();
    }
    @Bean
    public GroupedOpenApi studentApi() {
        return GroupedOpenApi.builder().group("学生管理模块")
                .pathsToMatch("/user/**", "/student/**")
                .build();
    }
}

application.yaml配置

springdoc:
  swagger-ui:
    path: /swagger-ui.html # 自定义Swagger前端请求路径
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs # Swagger后端请求地址
    enabled: true # 是否开启文档功能

# knife4j相关配置
knife4j:
  enable: true # 开启knife4j，无需添加@EnableKnife4j注解
  setting:
    language: zh_cn # 中文

4.常见注解

@Tag(name = "用户管理")//用于在控制器类上标注，指示该控制器的相关信息
@Operation(summary = "登录")//用于在控制器方法上标注，指示该方法的作用、描述等
@Schema(description = "用户信息")//在DTO类上标注，用于描述一个实体类
@Schema(description = "用户信息")//用于描述实体类的属性(自己定义的接收变量)，即类的字段
@Parameter(description = "邮箱") //定义在控制层方法的参数上

效果展示

访问路径

swagger-ui路径:http://localhost:8080/swagger-ui/index.html

swagger文档路径:http://127.0.0.1:8080/doc.html#/home

3.springfox集成swagger

该方式已经很久没有更新，SpringBoot3项目有兼容性问题

    <!--生成swagger接口文档-->
 <!--提供了一个简单的基于浏览器的界面，用于查看由 springfox-swagger2 生成的 API 文档-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
<!--Knife4j是Swagger-UI的增强版本,它不仅包括了 Swagger-UI 的所有功能，还增加了一些额外的功能-->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        <version>2.0.2</version>
    </dependency>
    <!--这是 Swagger 2 的核心库 它提供了注解（如 @Api, @ApiOperation 等）-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>

文档配置

package com.tanhua.sso.config;
 
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@Slf4j
public class WebMvcConfig implements WebMvcConfigurer {
    /**
     * 通过knife4j生成接口文档
     * @return
     */
    @Bean
    public Docket docket() {
        log.info("准备生成用户接口文档...");
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("java配置文档")
                .version("2.0")
                .description("https://blog.youkuaiyun.com/weixin_65019617")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .groupName("用户端接口")
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.tanhua.sso.controller"))//控制层路径
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
    /**
     * 设置静态资源映射
     * @param registry
     */
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        log.info("开始设置静态资源映射...");
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");//配置文档的路径
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

常见注解

@Api(tags = "查询用户id接口")//用于在控制器类上标注，指示该控制器的相关信息
@ApiOperation("测试")//用于在控制器方法上标注，指示该方法的作用、描述等
@ApiModel("用户登录DTO")//在DTO类上标注，用于描述一个实体类
@ApiModelProperty("登录用户名")//用于描述实体类的属性(自己定义的接收变量)，即类的字段

效果展示

访问路径

swagger-ui路径:http://localhost:18080/swagger-ui.htm

swagger文档路径:http://localhost:18080/doc.html

二、集成JWT

导入依赖

        <dependency>
			<groupId>io.jsonwebtoken</groupId>
			<artifactId>jjwt</artifactId>
			<version>0.9.1</version>
		</dependency>

工具包

public static String createJWT(String secretKey, long ttlMillis, Map<String, Object> claims) {
        // 指定签名的时候使用的签名算法(SHA256withDSA加密算法)，也就是header那部分,使用需要导入依赖
        SignatureAlgorithm signatureAlgorithm = SignatureAlgorithm.HS256;
 
        // 生成JWT的时间
        long expMillis = System.currentTimeMillis() + ttlMillis;
        Date exp = new Date(expMillis);
 
        // 设置jwt的body
        JwtBuilder builder = Jwts.builder()
                // 如果有私有声明，一定要先设置这个自己创建的私有的声明，这个是给builder的claim赋值，一旦写在标准的声明赋值之后，就是覆盖了那些标准的声明的
                .setClaims(claims)
                // 设置签名使用的签名算法和签名使用的秘钥
                .signWith(signatureAlgorithm, secretKey.getBytes(StandardCharsets.UTF_8))
                // 设置过期时间
                .setExpiration(exp);
 
        return builder.compact();
    }
 
    /**
     * Token解密
     *
     * @param secretKey jwt秘钥 此秘钥一定要保留好在服务端, 不能暴露出去, 否则sign就可以被伪造, 如果对接多个客户端建议改造成多个
     * @param token     加密后的token
     * @return
     */
    public static Claims parseJWT(String secretKey, String token) {
        // 得到DefaultJwtParser
        Claims claims = Jwts.parser()
                // 设置签名的秘钥
                .setSigningKey(secretKey.getBytes(StandardCharsets.UTF_8))
                // 设置需要解析的jwt
                .parseClaimsJws(token).getBody();
        return claims;
    }
 
}