Spring Boot项目集成Knife4j接口文档的实例代码

Spring Boot项目集成Knife4j接口文档的实例代码

目录1、在pom.xml引入依赖包2、创建Knife4j配置文件3、使用Knife4j注解4、全局参数

Knife4j就相当于是swagger的升级版，对于我来说，它比swagger要好用得多

1、在pom.xml引入依赖包

com.github.xiaoymin

knife4j-shttp://pring-boot-starter

2.0.9

2、创建Knife4j配置文件

package com.yuyun.config;

import io.swagger.annotations.ApiOperation;

import io.swagger.models.auth.In;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.service.ApiKey;

import springfox.documentation.service.Contact;

import springfox.documentation.service.SecurityScheme;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

import java.util.ArrayList;

import java.util.List;

/**

* @author hyh

*/

@Configuration

@EnableSwagger2WebMvc

public class Knife4jConfiguration {

@Bean(value = "defaultApi2")

public Docket defaultApi2() {

Docket docket = new Docket(DocumentationType.SWAGGER_2)

// 是否启用Swagger

.enable(true)

//分组名称

.groupName("1.0版本")

// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）

.apiInfo(apiInfo())

// 设置哪些接口暴露给Swagger展示

.select()

// 扫描所有有注解的api，用这种方式更灵活

.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

//指定Controller扫描包路径

// .apis(RequestHandlerSelectors.basePackage("com.yuyun.controller"))

// 扫描所有

// .apis(RequestHandlerSelectors.any())

.build();

return docket;

}

private ApiInfo apiInfo() {

String name = "雨云";

String url = "https://xxx.com/";

String email = "1873591403@qq.com";

Contact contact = new Contact(name, url, email);

return new ApiInfoBuilder()

.title("API接口文档")

.description("API接口文档描述")

.termsOfServiceUrl("https://xx.com/")

.contact(contact)

.version("1.0.1")

.build();

}

}

注意：如果出现错误Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

是因为SpringBoot版本高了，将版本降下去或者在application.yml添加如下内容即可解决该错误

spring:

mvc:

pathmatch:

matching-strategy: ant_path_matcher

项目运行后，访问ip+端口号+/doc.html，比如http://localhost:8110/doc.html。效果如图

3、使用Knife4j注解

（1）在实体类中使用

@ApiModel 放在在响应实体类上，用于描述该类

@ApiModelProperty 描述该响应类的属性

/**

* 企业信息表

*

* @author

* @since 1.0.0 2021-12-17

*/

@Data

@ApiModel(value = "企业信息表")

@TableName("company")

public class CompanyDTO implements Serializable {

private static final long serialVersionUID = 1L;

/**

* 主键

*/

@ApiModelProperty(value = "主键")

private Long id;

/**

* 企业名称

*/

@ApiModelProperty(value = "企业名称")

private String companyName;

/**

* 简介

*/

@ApiModelProperty(value = "简介")

private String description;

}

（2）在Controller层使用

@RestController

@RequestMapping("company")

@Api(tags = "企业信息表")

public class CompanyController {

@Autowired

private CompanyService companyService;

@GetMapping("getList")

@ApiOperation("根据条件获取数据http://")

@ApiImplicitParams({

@ApiImplicitParam(name = "id", value = "id", paramType = "query", required = true, dataType = "String"),

@ApiImplicitParam(name = "name", value = "名称", paramType = "query", required = true, dataType = "String")

})

public Result> getList(@ApiParam(name = "address", value = "地址", required = true) String address) {

List companyList = companyService.list();

return new Result>().success(companyList);

}

}

还有其他一些注解，用到再了解

4、全局参数

在实际项目中访问接口都添加了权限，每次访问都要带一个请求头参数token。全局参数就是为了方便传一个固定的参数。当添加全局参数后，所有的接口都会带上该参数。

第一种

在配置文件中加入

private List securitySchemes() {

List apiKeyList = new ArrayList();

apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));

return apiKeyList;

}

在defaultApi2()方法内引用

.securitySchemes(securitySchemes())

最后配置文件中的内容：

@Configuration

@EnableSwagger2WebMvc

public class Knife4jConfiguration {

@Bean(value = "defaultApi2")

public Docket defaultApi2() {

Docket docket = new Docket(DocumentationType.SWAGGER_2)

// 是否启用Swagger

.enable(true)

//分组名称

.groupName("1.0版本")

// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）

.apiInfo(apiInfo())

// 设置哪些接口暴露给Swagger展示

.select()

// 扫描所有有注解的api，用这种方式更灵活

.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

//指定Controller扫描包路径

// .apis(RequestHandlerSelectors.basePackage("com.yuyun.controller"))

// 扫描所有

// .apis(RequestHandlerSelectors.any())

.paths(PathSelectors.any())

.build()

/* 设置安全模式，swagger可以设置访问token */

.securitySchemes(securitySchemes())

.securityContexts(securityContexts())

.pathMapping("/");

return docket;

}

private ApiInfo apiInfo() {

String name = "雨云";

String url = "https://xxx.com/";

String email = "1873591403@qq.com";

Contact contact = new Contact(name, url, email);

return new ApiInfoBuilder()

.title("API接口文档")

.description("API接口文档描述")

.termsOfServiceUrl("https://xx.com/")

.contact(contact)

.version("1.0.1")

.build();

}

/**

* 安全模式，这里指定token通过Authorization头请求头传递

*/

private List securitySchemes() {

List apiKeyList = new ArrayList();

apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));

return apiKeyList;

}

/**

* 安全上下文

*/

private List securityContexts() {

List securityContexts = new ArrayList<>();

securityContexts.add(

SecurityContext.builder()

.securityReferences(defaultAuth())

.build());

return securityContexts;

}

/**

* 默认的安全上引用

*/

private List defaultAuth() {

AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");

AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];

authorizationScopes[0] = authorizationScope;

List securityReferences = new ArrayList<>();

securityReferences.add(new SecurityReference("Authorization", authorizationScopes));

return securityReferences;

}

}

效果：菜单上多了一个Authorize，在参数值中添加上信息

刷新一下，再打开接口就会发现多了个请求头部

第二种

直接在菜单文档管理→全局参数设置，然后添加参数：

再打开接口就会发现请求头参数加上了

源码地址：https://gitee.com/hyh17808770899/spring-boot/tree/master/springboot-03

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。