背景

开发最不想干的事是什么？那一定是写文档，相对于敲代码，写文档实在是太难了，尤其是接口文档。那么有需求，就有市场，于是就有Swagger应运而生，不止于此，相伴而生的还有了很多基于Swagger的接口ui界面面，比如Swagger ui，SwaggerBootstrap UI，knife4j等。那么其中最美的当然是今天我们的主角knife4j，没有之一。那么我们就直接上干货吧！

优点

1. 采用左右布局，更符合我们的审美，操作方便
2. 一键复制接口，复制文档，复制接口地址
3. 自动生成请求样例报文，及返回报文
4. 注解可以自动注入参数说明及填写要求
5. 集成简单

环境

1. jdk1.8+
2. springboot 2.5.6
3. knife4j 2.0.4

搭建

pom文件引入依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.4</version>
</dependency>

定义配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * Swagger2 API
     * @author: liyajie
     * @date: 2021/2/19 16:08
     * @param
     * @return: springfox.documentation.spring.web.plugins.Docket
     * @exception:
     * @update:
     * @updatePerson:
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(this.apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.lyj.knife4j"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * API 接口描述
     * @author: liyajie
     * @date: 2021/2/19 16:08
     * @param
     * @return: springfox.documentation.spring.web.plugins.Docket
     * @exception:
     * @update:
     * @updatePerson:
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .contact("李亚杰<17710557864@163.com>")
                .title("RestAPI文档")
                .description("RestAPI文档")
                .version("1.0.0-DEV")
                .build();
    }
}

常用注解

1. @Api：用在controller类上，主要标明接口api一级分类名称

image.png

2. @ApiOperation：用在方法上，主要标明接口api名称

image.png

3. @ApiModel：用在入参dto类上，主要是标明参数类的名称

image.png

4. @ApiModelProperty: 用在参数dto类的属性上，主要是标明dto属性的说明及样例

image.png

测试

启动项目后，访问地址http://ip:port/doc.html即可

image.png

image.png

注意点

现在流行的springboot集成knife4j时一定要注意版本的兼容问题，比如小编开始使用时，springboot的版本是2.6.2，然后knife4j的版本是2.0.4，配置完成后项目就启不来了。所以版本兼容很重要！

需要源码的可以关注公众号【温故知新之java】，更多干活与你分享。