【SpringBoot】SpringBoot引入接口文档生成工具（Swagger+Knife4j)

原创已于 2024-01-24 16:24:45 修改 · 1.9k 阅读

23 ·

CC 4.0 BY-SA版权

文章标签：

#spring boot #后端 #java

于 2024-01-22 00:56:29 首次发布

Java web 专栏收录该内容

27 篇文章

订阅专栏

一、前言

由于目前工作项目写的接口越来越多了，为了能够更加方便地优化接口，以及整理接口文档，所以就考虑引入接口文档生成工具。目前的接口文档生成工具被提及较多的是Swagger，经过了引入尝试后，Swagger是比较轻松地就被引入了。但是Swagger页面属实是难以恭维，比较简单但是不美观。于是经过我再一轮的技术调研后，我发现了一个国产的技术框架——Knife4j，Knife4j是结合了Swagger，并在此基础上更精致了页面的一项技术。接下来我将以springboot2和3的环境中分别介绍，讲述如何在Springboot中引入Knife4j。

二、基于Springboot2

maven依赖引入

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--在引用时请在maven中央仓库搜索最新版本号-->
    <version>3.0.3</version>
</dependency>

在启动类上加注解@EnableOpenApi

@EnableOpenApi
@SpringBootApplication
@MapperScan("com.example.mapper")
public class DemoApplication {

    public static void main(String[] args) {
        //SpringApplication.run(DemoApplication.class, args);
        new SpringApplicationBuilder(DemoApplication.class).run(args);
    }

}

编写配置类

@Configuration
@EnableSwagger2
//下面两条是Knife4j引入的，若是只用Swagger可去掉
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {
    /**
     * Swagger配置 for Knife4j
     * @return
     */
    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(
                        new ApiInfoBuilder()
                                // 文档标题
                                .title("title")
                                // 文档描述信息
                                .description("content")
                                .contact(new Contact("peng_YunJun","https://blog.youkuaiyun.com/peng_YuJun?type=blog","pengyujun53@163.com"))
                                // 文档版本号
                                .version("1.0")
                                .build()
                )
                //分组名称
                .groupName("Swagger在线文档")
                // select()：生成 API 文档的选择器，用于指定要生成哪些 API 文档
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                // paths()：指定要生成哪个 URL 匹配模式下的 API 文档。这里使用 PathSelectors.any()，表示生成所有的 API 文档。
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

}

常用注解

@APi：用在请求的类上，例如Controller，表示对类的说明
@ApiOperation：用在请求的方法上，说明方法的用途、作用
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApilmplicitParams注解中，指定请求参数的各个方法
@ApiParam：用在请求的类的形参上
@ApiModel：用在类上，通常是实体类，表示一个返回响应数据的信息
@ApiModelProperty：用在属性上，描述响应类的属性

使用例子

@RestController
@RequestMapping("appointment")
@Api(tags = "Appointment信息请求类")
public class AppointmentController {
    /**
     * 服务对象 
     */
    @Resource
    private AppointmentService appointmentService;

    /**
     * 分页查询
     * @param currentPage
     * @param pageSize
     * @param appointment 筛选条件
     * @return 查询结果
     */
    @ApiOperation(value = "分页查询" notes = "额外说明")
    @GetMapping("getPage")
    public ResponseData getPage(Integer currentPage, Integer pageSize, Appointment appointment) {
        if (currentPage == null || pageSize == null){
            return new ResponseData(HttpStatusEnum.BAD_REQUEST.getCode(), HttpStatusEnum.BAD_REQUEST.getMessage());
        }
        return appointmentService.getByPage(currentPage, pageSize, appointment);
    }

    /**
     * 通过主键查询单条数据
     *
     * @param id 主键
     * @return 单条数据
     */
    @ApiOperation("根据ID查询信息")
    @GetMapping("findById")
    public ResponseData findById(Long id) {
        if (id == null){
            return new ResponseData(HttpStatusEnum.BAD_REQUEST.getCode(),HttpStatusEnum.BAD_REQUEST.getMessage());
        }
        return appointmentService.findById(id);
    }
}

@ApiModel(value = "ResponseDate",description = "统一前端响应格式")
public final class ResponseData<T> {
    @ApiModelProperty(name = "code",value = "响应代码", example = "200")
    private Integer code;
    @ApiModelProperty(name = "msg",value = "响应信息",example = "添加成功")
    private String msg;
    @ApiModelProperty(name = "data",value = "响应数据",example = "响应数据/空")
    private T data;
}

运行

启动服务，工程启动起来，访问http://localhost:{该服务的端口号}/doc.html查看接口信息和进行测试

三、基于Springboot3

maven依赖引入

<!--    集成了swagger的文档网页自动生成工具    -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>

编写配置类

/** 接口文档生成配置
 * 可以通过 /doc.html 访问接口文档
 */
@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("xxx平台-API接口文档")
                        //描叙
                        .description("这是基于Knife4j OpenApi3的接口文档")
                        //版本
                        .version("v1.0")
                        //作者信息，自行设置
                        .contact(new Contact().name("xxx").email("xxx@xx.com").url("https://www.baidu.com"))
                        //设置接口文档的许可证信息
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("xxx平台-主页")
                        .url("http://127.0.0.1:8080/index"));
    }

}

常用注解

这里与springboot2使用的依赖不一样，Springfox改用Springdoc后，注解改变：
@Api → @Tag
@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiOperation(value = “foo”, notes = “bar”) → @Operation(summary = “foo”, description = “bar”)
@ApiParam → @Parameter
@ApiResponse(code = 404, message = “foo”) → @ApiResponse(responseCode = “404”, description = “foo”)

使用例子

@RestController
@RequestMapping("api")
@Tag(name = "App接口请求类")
public class AppApiController {

    @Resource
    private UserService userService = new UserService();

    @Operation(summary = "APP登录系统")
    @LogAnnotation(info = "APP登录系统", logtypeid = Constants.loginLogTypeId)
    @PostMapping("login")
    @ResponseBody
    public Map<String, Object> login(String phone_num, String password, HttpSession session) {
        if (!StringUtils.hasText(phone_num) || !StringUtils.hasText(password)) {
            Map<String, Object> resultMap = new HashMap<>();
            resultMap.put("code", RequestResultEnum.BAD_REQUEST.getCode());
            resultMap.put("msg", RequestResultEnum.BAD_REQUEST.getMessage());
            return resultMap;
        }
        Map<String, Object> map = userService.loginAccount(phone_num, password);
        return map;
    }
}

@Schema(description = "用户实体")
public class User {
    @Schema(description = "用户名称")
    private String userName;
    @Schema(description = "密码")
    private String password;
    @Schema(description = "邮箱")
    private String email;

    @Schema(description = "年龄")
    private int age;
    //...
}

运行

启动服务，工程启动起来，访问http://localhost:{该服务的端口号}/doc.html查看接口信息和进行测试

四、问题

若是一个实体一个属性有多个get或set方法，会发生报错。
因为Swagger无法确定用哪一个get或set方法，所以就会冲突报错。用注解@JsonProperty(“属性名”)可以解决，放置在其中一个get或set方法上，用于指定映射关系。
如何设置请求头函数
因为在当前项目中需要在请求头中携带一个Authorization为名的jwt作为登录验证，只有携带jwt的请求能够成功获取数据，所以在这一限制下，无法直接用Knife4j提供的调试功能进行调试。那么应该如何设置请求头呢，下面是一些配置代码。调整一下原有的Swagger配置类就可以了，之后查看调试功能，就可以看到请求头设置处会有一个参数等着你去设置的。

@Configuration
public class SwaggerConfig {

    @Resource(name = "isLoginFilterRegistrationBean")
    private FilterRegistrationBean isLoginFilterRegistrationBean;

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("安全生产综合信息管理平台-API接口文档")
                        //描叙
                        .description("这是基于Knife4j OpenApi3的接口文档")
                        //版本
                        .version("v1.0")
                        //作者信息，自行设置
                        .contact(new Contact().name("xxx").email("xxx@xx.com").url("https://www.baidu.com"))
                        //设置接口文档的许可证信息
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("安全生产综合信息管理平台-主页")
                        .url("http://127.0.0.1:8081/Manage/index"))
                // 配置全局鉴权参数-Authorize
                .components(new Components()
                        .addSecuritySchemes(HttpHeaders.AUTHORIZATION,
                                new SecurityScheme()
                                        .name(HttpHeaders.AUTHORIZATION)
                                        .type(SecurityScheme.Type.APIKEY)
                                        .in(SecurityScheme.In.HEADER)
                                        .scheme("Bearer")
                                        .bearerFormat("JWT")
                        ));
    }

    /**
     * 全局自定义扩展
     * <p>
     * 在OpenAPI规范中，Operation 是一个表示 API 端点（Endpoint）或操作的对象。
     * 每个路径（Path）对象可以包含一个或多个 Operation 对象，用于描述与该路径相关联的不同 HTTP 方法（例如 GET、POST、PUT 等）。
     */
    @Bean
    public GlobalOpenApiCustomizer globalOpenApiCustomizer() {
        //获取忽略拦截的名单
        Map<String, String> initParameters = isLoginFilterRegistrationBean.getInitParameters();
        String excludedUrisStr = initParameters.get("excludedUris");
        String[] excludedUris = null;
        if (StringUtils.hasText(excludedUrisStr)) {
            excludedUris = excludedUrisStr.split(",");
        }
        String[] finalExcludedUris = excludedUris;
        return openApi -> {
            // 全局添加鉴权参数
            if (openApi.getPaths() != null) {
                openApi.getPaths().forEach((s, pathItem) -> {
                    // 定义表示变量 并验证Path 是否包含不过滤路径，若包含则不需要添加鉴权参数
                    boolean flag = finalExcludedUris != null && Arrays.stream(finalExcludedUris).anyMatch(s::contains);
                    if(!flag) { //不在忽略拦截名单上，需要拦截
                        // 接口添加鉴权参数
                        pathItem.readOperations()
                                .forEach(operation ->
                                        operation.addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION))
                                );
                    }
                });
            }
        };
    }

}