目录
API文档集成与增强
集成open api
官网文档: springdoc-openapi
- 依赖导入
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.11</version>
</dependency>
- 配置文件设置
# open api配置
springdoc:
packages-to-scan: com.example.swagger3knife4j.controller
swagger-ui:
enabled: true
api-docs:
enabled: true
- 文档设置
@Configuration
public class OpenApiConfig {
@Bean
public OpenAPI api() {
return new OpenAPI().info(new Info().title("文档标题")
.description("文档描述")
.version("v1.0.0"));
}
}
到此配置就完成了，接下来便是使用open api的规范来生成对应的API文档
open api使用方法
- 首先通过@Tag给文档添加注释，通过@Operation给每个接口添加文档注释
@Tag(name = "用户接口")
@RestController
@RequestMapping(PRIVATE_PATH + "/user")
public class UserController {
@GetMapping("/getOneUser")
@Operation(summary = "随机获取一个用户")
public User getOneUser() {
return new User("姓名", "13899999999");
}
}
- 通过@Schema给自定义对象（入参和返回相同）添加文档注释
@Data
@AllArgsConstructor
@Schema(description = "用户信息")
public class User {
@Schema(description = "姓名")
private String name;
@Schema(description = "电话")
private String phone;
}
- 访问地址：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
- 依赖导入
<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添加相应的文件目录
- 在此前为的配置文件OpenApiConfig中，添加Knife4j的文档设置，这里所有前缀为“PRIVATE_PATH”的接口，都用过“基础接口”这个目录来访问
@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("基础接口")
.pathsToMatch(PRIVATE_PATH + "/**")
.build();
}
此时重启，Knife4j的页面内容如下：
- 相关功能点介绍
- 主页：展示了一些接口的统计信息
- SwaggerModels：展示了所有的传输对象
- 文档管理：提供全局参数设置（如在请求头添加token登）、离线文档下载（Knife4j提供导出4种格式的离线文档(Html/Markdown/Word/OpenAPI)）、以及一些其它个性化设置。
- “用户接口”：这些目录就是我们生成好的接口文档了。
API文档的常用内容
为@PathVariable的参数添加文档注释
添加@Parameter参数就行
@GetMapping("/getName/{userName}")
@Operation(summary = "获取用户名")
public String getName(@Parameter(required = true, name = "userName", description = "用户名")
@PathVariable("userName") String userName) {
return userName;
}
接口分组
接口分组的方式很简单，即在文件中设置其它分组，同时设置不同的请求路径即可
@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("公共接口")
.pathsToMatch(PUBLIC_PATH + "/**")
.build();
}
@Bean
public GroupedOpenApi privateApi() {
return GroupedOpenApi.builder()
.group("私有接口")
.pathsToMatch(PRIVATE_PATH + "/**")
.build();
}
设置全局请求头（token）
如果需要为某个分组添加必填字段的话，可以通过如下方式实现：
@Bean
public GroupedOpenApi tokenApi(OperationCustomizer operationCustomizer) {
return GroupedOpenApi.builder()
.group("鉴权")
.pathsToMatch(PRIVATE_PATH + "/**")
.addOperationCustomizer(operationCustomizer)
.build();
}
@Bean
public OperationCustomizer operationCustomizer() {
return (operation, handlerMethod) -> operation.addParametersItem(
new Parameter()
.in("header")
.required(true)
.description("token 验证")
.name("token"));
}
此时该分组的接口，必须传递该字段（当然这只是一种规范，实际请求时还需要自行加上token登必传字段的校验）
在使用文档时，可以在全局参数设置中添加改参数，避免每个接口都要再填一遍（确定后刷新生效）。
在特定环境屏蔽API文档
开发和测试环境需要文档，但是上线之后，就必须把这些文档给屏蔽调。
比如生成环境prod，只需要在生成环境的yml文件中需改如下springdoc的配置即可：
springdoc:
packages-to-scan: com.example.swagger3knife4j.controller
swagger-ui:
enabled: false
api-docs:
enabled: false
源码地址
源码: github仓库地址