Knife4j增强版Swagger

前言

swagger 一般都很熟悉了,一个可以生成 Rest 风格接口文档的工具,虽然使用了侵入代码式的方式,但却减少了重复变更接口带来的繁杂操作,但是在我周围实际使用中,真的很少又在用它来测试接口功能,它的风格似乎不符合国人的审美,更多的是使用 PostMan 来测试
最近发现了一个新的美化版的 Swagger 工具,Knif4J,基本可以满足简单的测试需求

官方文档传送门:传送门

配置使用

这里默认用户是 JAVA 语言,SpringBoot 开发的

引入依赖

推荐使用 starter 依赖,如下

1
2
3
4
5
6
<!-- https://mvnrepository.com/artifact/com.gitee.sophis/spring-boot-knif4j-starter -->
<dependency>
<groupId>com.gitee.sophis</groupId>
<artifactId>spring-boot-knif4j-starter</artifactId>
<version>latest version</version>
</dependency>

或者你也可以使用以下依赖组合,效果是一致的

1
2
3
4
5
6
7
8
9
10
11
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>

<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>${lastVersion}</version>
</dependency>

编写 Swagger2Config 配置文件

和 Swagger2 是一致的,这里读取的是 yml 配置信息,所以多了个 yml 处理器

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
30
31
32
33
34
35
36
37
38
39
40
41
@Configuration
@EnableSwagger2
@EnableKnife4j
@Setter
@PropertySource(value = "classpath:config/swagger.yml", factory = YamlPropertyResourceFactory.class)
@ConfigurationProperties(prefix = "swagger")
public class SwaggerConfiguration {

private String title;

private String version;

private String description;

private String name;

private String url;

private String email;


@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.bwensun.web"))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.contact(new Contact(name, url, email))
.title(title)
.description(description)
.termsOfServiceUrl("https://www.zoombar.fun")
.version(version)
.build();
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
public class YamlPropertyResourceFactory implements PropertySourceFactory {

/**
* Create a {@link PropertySource} that wraps the given resource.
*
* @param name the name of the property source
* @param encodedResource the resource (potentially encoded) to wrap
* @return the new {@link PropertySource} (never {@code null})
* @throws IOException if resource resolution failed
*/
@Override
public PropertySource<?> createPropertySource(@Nullable String name, EncodedResource encodedResource) throws IOException {
String resourceName = Optional.ofNullable(name).orElse(encodedResource.getResource().getFilename());
//yaml资源文件
if (Objects.requireNonNull(resourceName).endsWith(".yml") || resourceName.endsWith(".yaml")) {
List<PropertySource<?>> yamlSources = new YamlPropertySourceLoader().load(resourceName, encodedResource.getResource());
return yamlSources.get(0);
} else {//返回空的Properties
return new PropertiesPropertySource(resourceName, new Properties());
}
}
}
1
2
3
4
5
6
7
swagger:
title: Zoombar后端服务
version: 1.0.0
description: Zoombar游戏论坛
name: 孙博文
url: www.bwensun.top
email: bwensun@foxmail.com

测试使用

可以看到界面还是非常美观的,对于接口也支持了多种数据方式传输进行调试,总的来说还是比较满意的,另外 Knife4J 也支持接口信息的导出,这边就可以将它视为 YAPI 一样的接口文档平台来使用
image.png
image.png

Swagger2 注解信息一览

注解 作用
@Api 修饰整个类,描述 Controller 的作用
@ApiOperation 描述一个类的一个方法,或者说一个接口
@ApiParam 单个参数描述
@ApiModel 用对象来接收参数
@ApiProperty 用对象接收参数时,描述对象的一个字段
@ApiResponse HTTP 响应其中 1 个描述
@ApiResponses HTTP 响应整体描述
@ApiIgnore 使用该注解忽略这个 API
@ApiError 发生错误返回的信息
@ApiImplicitParam 一个请求参数
@ApiImplicitParams 多个请求参数

相关

  1. knife4j knife4j 是为 Java MVC 框架集成 Swagger 生成 Api 文档的增强解决方案
  2. Spring Boot 整合 Swagger2 构建 RESTful API
作者

孙博文

发布于

2020-08-20

更新于

2021-07-18

许可协议

评论