一分钟教你打造高效接口文档（Swagger+knife4j）

在前后端分离开发过程中，前端人员和后端人员要进行配合来共同完成一个开发任务，这个时候需要使用到接口（API接口：是一个http的请求地址，主要是定义：请求路径、请求方式、请求参数、响应数据等内容）。

• 后端编写和维护接口文档，在 API 变化时更新接口文档
• 后端根据接口文档进行接口开发
• 前端根据接口文档进行开发
• 开发完成后联调和提交测试

? 后端开发人员为前端提供接口的同时，还需同时提供接口的说明文档。但我们的代码总是会根据实际情况来实时更新，这个时候有可能会忘记更新接口的说明文档，造成一些不必要的问题，此时我们可以通过一些工具生成接口文档，做到文档实时更新，Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档。

**官方文档地址：**https://doc.xiaominfo.com/

Knife4j是一个集Swagger2 和 OpenAPI3 为一体的增强解决方案。

使用步骤

第一步：创建Spring Boot项目并且在pom.xml中引入Knife4j的依赖包，代码如下：

<!--引入Knife4j的官方start包,选择Spring Boot版本<3.0,开发者需要注意-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

第二步：创建Swagger配置依赖，代码如下：：

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean
    public Docket ApiConfig() {
        //指定使用Swagger2规范
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //分组名称
                .groupName("xxx后端服务")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.sun.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
    
     private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("xxx-API文档")
         		//描述字段支持Markdown语法
                .description("本文档描述了xxx微服务接口定义")
                .version("1.0")
                .contact(new Contact("xxx", "http://xxx.com", "xxx"))
                .build();
    }
}

第三步:新建一个接口Controller类，如下：

@Api(tags = "首页模块")
@RestController
public class IndexController {

    @ApiImplicitParam(name = "name",value = "姓名",required = true)
    @ApiOperation(value = "问好接口")
    @GetMapping("/sayHi")
    public ResponseEntity<String> sayHi(@RequestParam(value = "name")String name){
        return ResponseEntity.ok("Hi:"+name);
    }
}

第三步：万事俱备，启动Spring Boot项目，浏览器访问Knife4j的文档地址即可查看效果

http://localhost:8080/doc.html