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

客官°小女子只卖身不卖艺 2024-02-05 15:42 19阅读 0赞

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

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

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

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

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

![image-20231214104659396][]

#### 使用步骤 ####

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

<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

[image-20231214104659396]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/05/cabc28115ec941378487818190cf882f.png
[Knife4j]: https://search.maven.org/search?q=g:com.github.xiaoymin