Java 后端整合 Swagger 和 Knife4j 接口文档

一、接口文档的介绍

1. 什么是接口文档？

• 接口信息：请求参数、响应参数、接口地址、接口名称、请求类型、请求格式、备注

2. 谁在使用接口文档？

• 提供方：后端开发者或者项目负责人

• 使用方：后端和前端开发者

3. 为什么需要接口文档？

• 项目交接时便于接手新项目的开发人员通过查看接口文档熟悉项目，便于大家参考和查阅，便于项目的沉淀和维护

• 便于前后端开发对接，可以看作前后端联调的介质

• 好的接口文档接口在线调试、在线测试，作为工具来提高开发测试的效率

4. 怎么实现接口文档？

• 手写：腾讯文档、Markdown 笔记

• 自动化生成接口文档：自动根据项目代码生成完整的文档或在线调试的网页

  • Swagger

  • Postman（侧重于接口管理）

  • 国内：Apifox、Apipost、Eolink

5. Swagger 的原理

• 引入依赖（Swagger 或 Knife4j）

• 自定义 Swagger 配置类

• 指定需要生成接口文档的代码位置（Controller）

• 注意！线上环境不要向外部暴露接口！！

  • 解决方式：在 SwaggerConfig 配置文件开头添加以下限定配置，注明仅在部分环境开启接口文档

  @Profile({"dev", "test"})

• 启动项目之后，直接访问自动生成的接口文档即可

6. 使用接口文档的技巧

• 在 controller 方法上添加以下注解来自定义生成的接口描述信息：使接口文档更加清晰易读
  • @Api：用于标识一个 Controller 类，表示该类中的接口将会被包含在生成的接口文档中
  • @ApiImplicitParam(name = "name",value = "姓名",required = true)：用于描述一个方法的参数，通过指定参数名、值和是否必需来生成接口文档中的参数描述
  • @ApiOperation(value = "向客人问好") ：用于描述一个方法的作用，通过指定方法的名称和详细描述来生成接口文档中的接口描述

二、Java 整合 Knife4j 的详细步骤

参考官方文档：Knife4j · 集Swagger2及OpenAPI3为一体的增强解决方案. | Knife4j (xiaominfo.com)

1. 添加依赖

• 在 pom.xml 中引入 Knife4j 的依赖
• Knife4j是一个集Swagger2 和 OpenAPI3 为一体的增强解决方案

        
            com.github.xiaoymin
            knife4j-spring-boot-starter
            3.0.3
        

2. 添加配置类

package com.example.usercenter.config;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

/**
 * 自定义 Swagger 接口文档的配置
 *
 * @author 程序员鱼皮
 * @from 编程导航知识星球
 */
@Configuration
@EnableSwagger2WebMvc
@Profile({"dev", "test"})
public class SwaggerConfig {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 这里一定要标注你控制器的位置
                .apis(RequestHandlerSelectors.basePackage("com.yupi.yupao.controller"))
                .paths(PathSelectors.any())
                .build();
    }


    /**
     * api 信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("逐浪用户中心")
                .description("逐浪用户中心接口文档")
                .termsOfServiceUrl("https://github.com/lvxinxinL")
                .contact(new Contact("乐小鑫","https://github.com/lvxinxinL","[email protected]"))
                .version("1.0")
                .build();
    }
}

3. 启动项目，查看接口文档（报错解决记录）

• 踩坑：启动项目，遇到以下报错

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

• 报错原因：Springboot2.6 以后将 SpringMVC 默认路径匹配策略从 AntPathMatcher 更改为 PathPatternParser，导致出错
• 解决方法：在 application.yml 中添加以下配置修改 SpringMVC 的默认路径匹配策为 AntPathMatcher

spring: 
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

• 访问 localhost:8080/doc.html 查看 Knife4j 生成的接口文档

4. 使用接口文档进行调试

• 以用户登录为例
  • 点击要调试的接口 userLogin
  • 点击调试，输入请求参数
  • 发送请求
  • 查看请求响应内容