最近发现Knife4j 挺好用的，写个笔记记录一下。
Knife4j 是 Swagger 的增强解决方案，提供了强大的文档生成能力，还增加了许多实用功能。
Knife4j 实战指南
Knife4j is a set of Swagger2 and OpenAPI3 (github.com)
一、引入依赖
首先，我们需要在 Maven 项目中引入 Knife4j 依赖。在 pom.xml 文件中添加如下依赖：
1
2
3
4
5
| <dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.2</version>
</dependency>
|
二、配置 Knife4j
为了配置 Knife4j，我们需要在 Spring Boot 项目中添加一个配置类。在这个配置类中注册生成 API 文档所需的组件。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
|
@Configuration
@EnableSwaggerBootstrapUI
public class Knife4jConfiguration implements WebMvcConfigurer {
private static final Logger log = LoggerFactory.getLogger(Knife4jConfiguration.class);
@Bean
public Docket docket() {
ApiInfo apiInfo = new ApiInfoBuilder()
.title("项目接口文档")
.version("1.0")
.description("项目的接口文档")
.build();
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.select()
.apis(RequestHandlerSelectors.basePackage("com.dts.controller"))
.paths(PathSelectors.any())
.build();
}
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
|
三、常用注解
| 注解 |
说明 |
适用范围 |
@Api |
用于修饰整个类，描述 Controller 的作用 |
类 |
@ApiOperation |
用于方法，描述一个具体的操作 |
方法 |
@ApiParam |
用于方法参数，描述参数信息 |
方法参数 |
@ApiModel |
用于类，描述对象 |
类 |
@ApiModelProperty |
用于方法、字段，描述对象属性 |
方法、字段 |
@ApiResponse |
用于描述单个 HTTP 响应信息 |
方法 |
四、访问 API 文档
配置完成后，启动 Spring Boot 应用，访问 http://localhost:8080/doc.html 即可查看通过 Knife4j 生成的 API 文档。
