一文了解Spring boot + open api 3.0 + knife4j的集成实例，提供开发时常用的API配置

目录

API文档集成与增强

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

集成open api

官网文档: springdoc-openapi

1. 依赖导入

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>1.6.11</version></dependency>

1. 配置文件设置

# open api配置springdoc:packages-to-scan: com.example.swagger3knife4j.controller
  swagger-ui:enabled:trueapi-docs:enabled:true

1. 文档设置

@ConfigurationpublicclassOpenApiConfig{@BeanpublicOpenAPIapi(){returnnewOpenAPI().info(newInfo().title("文档标题").description("文档描述").version("v1.0.0"));}}

到此配置就完成了，接下来便是使用open api的规范来生成对应的API文档

open api使用方法

1. 首先通过@Tag给文档添加注释，通过@Operation给每个接口添加文档注释

@Tag(name ="用户接口")@RestController@RequestMapping(PRIVATE_PATH+"/user")publicclassUserController{@GetMapping("/getOneUser")@Operation(summary ="随机获取一个用户")publicUsergetOneUser(){returnnewUser("姓名","13899999999");}}

1. 通过@Schema给自定义对象（入参和返回相同）添加文档注释

@Data@AllArgsConstructor@Schema(description ="用户信息")publicclassUser{@Schema(description ="姓名")privateString name;@Schema(description ="电话")privateString phone;}

1. 访问地址：http://localhost:8888/swagger-ui/index.html

到此一个简单的接口文档便生成了，下面是效果图：

实体注释：

如上就是open api3的全部设置，它是基于swagger-ui设计的，因此界面和swagger没什么区别。

不过open api3的注解与swagger2完全不同，下面是两者注解的对应关系，方便swagger2的使用者快速开发。

open api与swagger注解方法的对应关系

open api的注解与swagger的有很大区别，open api的写法更为简单易懂，在实际使用时也不会像swagger的注解那样让人迷惑。

如下是两者注解的对应关系：

官网链接: 官网链接

下面介绍一款swagger的增强框架—knife4j，它的界面美观性因人而异，但是在使用体验上绝对甩swagger界面好多倍。废话不多说，直接将knife4j撸进来。

集成knife4j

官网文档: Knife4j

1. 依赖导入

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-springdoc-ui</artifactId><version>3.0.3</version></dependency>

ok，配置好之后，直接访问Knife4j的界面试试：http://localhost:8888/doc.html

Swagger和Knife4j的访问地址不同，但是都可以修改。

• http://localhost:8888/swagger-ui/index.html
• http://localhost:8888/doc.html

这时，Knife4j的访问界面都是一片空白的，不过不用慌，因为我们还需要为Knife4j添加相应的文件目录

1. 在此前为的配置文件OpenApiConfig中，添加Knife4j的文档设置，这里所有前缀为“PRIVATE_PATH”的接口，都用过“基础接口”这个目录来访问

@BeanpublicGroupedOpenApipublicApi(){returnGroupedOpenApi.builder().group("基础接口").pathsToMatch(PRIVATE_PATH+"/**").build();}

此时重启，Knife4j的页面内容如下：

1. 相关功能点介绍

• 主页：展示了一些接口的统计信息
• SwaggerModels：展示了所有的传输对象
• 文档管理：提供全局参数设置（如在请求头添加token登）、离线文档下载（Knife4j提供导出4种格式的离线文档(Html/Markdown/Word/OpenAPI)）、以及一些其它个性化设置。
• “用户接口”：这些目录就是我们生成好的接口文档了。

API文档的常用内容

为@PathVariable的参数添加文档注释

添加@Parameter参数就行

@GetMapping("/getName/{userName}")@Operation(summary ="获取用户名")publicStringgetName(@Parameter(required =true, name ="userName", description ="用户名")@PathVariable("userName")String userName){return userName;}

接口分组

接口分组的方式很简单，即在文件中设置其它分组，同时设置不同的请求路径即可

@BeanpublicGroupedOpenApipublicApi(){returnGroupedOpenApi.builder().group("公共接口").pathsToMatch(PUBLIC_PATH+"/**").build();}@BeanpublicGroupedOpenApiprivateApi(){returnGroupedOpenApi.builder().group("私有接口").pathsToMatch(PRIVATE_PATH+"/**").build();}

设置全局请求头（token）

如果需要为某个分组添加必填字段的话，可以通过如下方式实现：

@BeanpublicGroupedOpenApitokenApi(OperationCustomizer operationCustomizer){returnGroupedOpenApi.builder().group("鉴权").pathsToMatch(PRIVATE_PATH+"/**").addOperationCustomizer(operationCustomizer).build();}@BeanpublicOperationCustomizeroperationCustomizer(){return(operation, handlerMethod)-> operation.addParametersItem(newParameter().in("header").required(true).description("token 验证").name("token"));}

此时该分组的接口，必须传递该字段（当然这只是一种规范，实际请求时还需要自行加上token登必传字段的校验）

在使用文档时，可以在全局参数设置中添加改参数，避免每个接口都要再填一遍（确定后刷新生效）。

在特定环境屏蔽API文档

开发和测试环境需要文档，但是上线之后，就必须把这些文档给屏蔽调。

比如生成环境prod，只需要在生成环境的yml文件中需改如下springdoc的配置即可：

springdoc:packages-to-scan: com.example.swagger3knife4j.controller
  swagger-ui:enabled:falseapi-docs:enabled:false

源码地址

源码: github仓库地址