Spring Boot整合knife4j实现Api文档

发布时间：2022-09-26 19:30

一、简介

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!
　knife4j的前身是swagger-bootstrap-ui，为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j

knife4j官方文档
码云仓库地址

二、项目搭建

1、maven引入

<dependencies>
    <dependency>
        <groupId>com.github.xiaoymingroupId>
        <artifactId>knife4j-spring-boot-starterartifactId>
        
        <version>2.0.2version>
    dependency>
dependencies>

knife4j仓库地址

2、创建Swagger配置文件

首先创建application-dev.yml和application-prod.yml开发和生产环境，最后在application.yml中配置当前环境，这样就可以在生产环境中关闭在线接口文档了。另外也可以使用注解@Profile设置环境

spring:
  profiles:
    active: dev

package com.csdn.demo1.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {

//如果要设置多个用户组，只需要在定义一个Docket并打上@Bean返回即可
   @Bean
   public Docket docket(Environment environment) {

        //设置要显示的在线接口文档环境
        Profiles profiles = Profiles.of("dev","test");
        //通过environment.acceptsProfiles判断是否处于当前自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
            	//是否在浏览器显示,如果一直要显示开启，就选择true
                .enable(flag)
             	//.enable(true)
                //分组名称
                .groupName("1.0版本")
                .select()
                //这里指定Controller扫描包路径(项目路径也行)
                .apis(RequestHandlerSelectors.basePackage("com.csdn.demo1.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口说明")
                .description("DEMO服务接口说明")
                .termsOfServiceUrl("http://localhost:8888/")
                .version("1.0")
                .build();
    }
}

三、knife项目使用

1、常用注解介绍

@Api()

作用在类上，用来标注该类具体实现内容。
参数：
tags：类标签，一般用来写类的名称或作用。（常用）
description：可描述描述该类作用。

@ApiOperation()

用于方法的说明
参数：
value ：方法说明（常用）
notes ：注释说明
httpMethod ：说明这个方法被请求的方式
response ：方法的返回值的类型

@ApiOperationSupport()

（knife4j增加特性）用于接口方法排序，作者信息描述等。
参数：
order：排序
author：作者信息

@ApiImplicitParam()

对单个参数的说明
参数：
name ：参数名。
value ：参数的具体意义，作用。（常用）
required ：参数是否必填。（常用）
dataType ：参数的数据类型。（常用）
paramType ：查询参数类型，这里有几种形式：
类型　　　　　作用
path 　　　以地址的形式提交数据
query 　　直接跟参数完成自动映射赋值
body　　　以流的形式提交仅支持POST
header　　参数在request headers 里边提交
form　　　以form表单的形式提交仅支持POST

@ApiModel()

用于描述一个数据模型的信息，即我们常用的实体、VO类、DTO类等描述
参数：
value ：数据模型名称。（常用）
description:具体描述
parent：父类

@ApiModelProperty()

用于描述数据模型的属性信息
参数：
value：字段说明（常用）
name：重写属性名字
dataType：重写属性类型
required：是否必填（常用）
example：举例说明（常用）
hidden：隐藏

@ApiIgnore

自动生成接口说明时忽略

2、项目中的简单使用

在项目启动中我还遇到了javax/validation/constraints/Min报错，原因是我使用了最新的springboot框架版本，新版本没有自动引入 validation对应的包，所以要想使用校验功能要手动引入包。在pom.xml引入依赖即可

<dependency>
	<groupId>org.springframework.bootgroupId>
	<artifactId>spring-boot-starter-validationartifactId>
 dependency>

启动项目后，访问http://localhost:8080/doc.html即可(ip和端口根据实际需求来)。根据接口的不同需求，结合官方文档，可以写出自己需要的个性化需求。下面是我自己测试的demo
官方文档参考

参考文章