Swagger & Knife4j
AlightYoung 12/15/2019 OpenAPI
推荐knife4j
# Knife4j
Knife4j的前身是swagger-bootstrap-ui，前身swagger-bootstrap-ui是一个纯swagger-ui的ui皮肤项目。
随着时间的推移，项目开始从一个Swagger的UI方案进化为一个为Swagger接口文档服务的通用性解决方案，因此改名为Knife4j。
下面记录了Knife4j与SpringBoot的集成，细节参考官方文档 (opens new window)
pom.xml：项目依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.2</version>
</dependency>
1
2
3
4
5
2
3
4
5
Knife4jConfiguration：配置类
@Configuration
@EnableSwagger2
public class Knife4jConfiguration {
@Bean(value = "defaultApi2")
public Docket defaultApi2() {
Docket docket=new Docket(DocumentationType.SWAGGER_2)
.apiInfo(new ApiInfoBuilder()
.description("default description")
.termsOfServiceUrl("url")
.contact(new Contact("name","url","email"))
.version("1.0")
.build())
.groupName("default group name")
.select()
// base package of controller
.apis(RequestHandlerSelectors.basePackage("com.xxx.xxx.controller"))
.paths(PathSelectors.any())
.build();
return docket;
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
Controller注解说明
@Api(tags = "xx模块")：Controller解释，标注在Controller头部。@ApiImplicitParam(name = "",value = "",required = true)：API参数解释，标注在Controller方法上。@ApiOperation(value = "")：API解释，标注在Controller方法上。
实体类注解说明
@ApiModel：作用于类上，解释实体类@ApiModelProperty：用于属性上，解释属性
最后，启动项目，打开http://localhost:{your server port}/doc.html查看效果即可。
# Swagger
Swagger是一个开放源代码软件框架，由大型工具生态系统支持，可帮助开发人员设计，构建，记录和使用RESTful Web服务。尽管大多数用户通过Swagger UI工具识别Swagger，但是Swagger工具集包括对自动文档，代码生成和测试用例生成的支持。
至于有人考虑swagger对代码的入侵性，这个就见仁见智了。此处提供一个简单的demo以供简单集成参考 gitee仓库地址 (opens new window)
zuul环境下与swagger的整合
zuul启动类加上@EnableSwagger2Doc注解
直接在启动类下编写配置
@Component
@Primary
class DocumentationConfig implements SwaggerResourcesProvider {
@Override
public List<SwaggerResource> get() {
List resources = new ArrayList<>();
// 通过服务别名获取swagger api
resources.add(swaggerResource("app-alight-member", "/app-alight-member/v2/api-docs", "2.0"));
resources.add(swaggerResource("app-alight-weixin", "/app-alight-weixin/v2/api-docs", "2.0"));
return resources;
}
private SwaggerResource swaggerResource(String name, String location, String version) {
SwaggerResource swaggerResource = new SwaggerResource();
swaggerResource.setName(name);
swaggerResource.setLocation(location);
swaggerResource.setSwaggerVersion(version);
return swaggerResource;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19