springboot整合knife4j
springboot整合knife4j
简介
官网地址：knife4j
Knife4j的前身是swagger-bootstrap-ui,前身swagger-bootstrap-ui是一个纯swagger-ui的ui皮肤项目。
一开始项目初衷是为了写一个增强版本的swagger的前端ui,但是随着项目的发展,面对越来越多的个性化需求,不得不编写后端Java代码以满足新的需求,在swagger-bootstrap-ui的1.8.5~1.9.6版本之间,采用的是后端Java代码和Ui都混合在一个Jar包里面的方式提供给开发者使用.这种方式虽说对于集成swagger来说很方便,只需要引入jar包即可,但是在微服务架构下显得有些臃肿。
因此,项目正式更名为knife4j,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端.
后端Java代码和ui包分离为多个模块的jar包,以面对在目前微服务架构下,更加方便的使用增强文档注解(使用SpringCloud微服务项目,只需要在网关层集成UI的jar包即可,因此分离前后端)。
依赖
<!-- 整合knife4j -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.8</version>
</dependency>
配置类
//通过配置类整合Swagger2
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {
/*引入Knife4j提供的扩展类*/
@Autowired
private OpenApiExtensionResolver openApiExtensionResolver;
@Bean("swagger2ConfigDefault")
public Docket swagger2ConfigDefault() {
Docket docket = new Docket(DocumentationType.SWAGGER_2); //选择swagger类型
docket.apiInfo(getApiInfo("我的swaggerDefault", "Default接口文档"))
.groupName("default")
.select() // 选择器
.apis(RequestHandlerSelectors.basePackage("com.conformity.general.controller")) // 扫描指定包下所有注解
.paths(PathSelectors.any()) // 指定路径范围 这里表示所有路径
.build() // 构建swagger文档对象
.extensions(openApiExtensionResolver.buildSettingExtensions());
return docket;
}
@Bean("swagger2ConfigCommon")
public Docket swagger2ConfigCommon() {
Docket docket = new Docket(DocumentationType.SWAGGER_2); //选择swagger类型
docket.apiInfo(getApiInfo("我的swaggerCommon", "Common接口文档"))
.groupName("Common")
.select() // 选择器
.apis(RequestHandlerSelectors.basePackage("com.conformity.general.controller")) // 扫描指定包下所有注解
.paths(PathSelectors.any()) // 指定路径范围 这里表示所有路径
.build() // 构建swagger文档对象
.extensions(openApiExtensionResolver.buildSettingExtensions());
return docket;
}
private ApiInfo getApiInfo(String title,String description) {
return new ApiInfoBuilder() //设置文档上下文信息
.title(title) // 文档标题
.description(description) // 简介
.version("1.0") // 版本
// 设置联系人 ： 作者 网站地址 邮箱
.contact(new Contact("lsx", "https://gitee.com/buluozhimu", "[email protected]"))
// 服务条款链接
.termsOfServiceUrl("https://gitee.com/buluozhimu")
// 认证许可
.license("my swagger -- test")
// 认证许可链接
.licenseUrl("https://www.baidu.com")
.build(); // 构建上下文对象a
}
}
界面
@Bean(“swagger2ConfigDefault”)和@Bean(“swagger2ConfigCommon”) 分为两个组，通过.groupName()方法进行分组
ApiInfo：构建主页信息
yml配置
knife4j:
enable: true #开启增强配置
production: false #开启生产环境屏蔽
basic: #基本的登录认证
enable: false
password: lsx
username: lsx
#自定义footer
setting:
enableFooter: false
enableFooterCustom: true
footerCustomContent: Apache License 2.0 | Copyright 2021-[英雄联盟](https://gitee.com/buluozhimu)
常用注解
- @Api(tags = {“测试Controller”}) 给controller 起别名 类注解
- @ApiOperation(“测试demo”) 方法的描述
- @ApiParam(name = “a”,value = “用户名”,required = true) 对参数的描述
- @ApiIgnore 忽略 标注方法 或者 参数 则不生成对应文档
- @ApiImplicitParams
@ApiImplicitParams({ //描述方法上的参数 功能和ApiParam 差不多 差别在于作用于方法上
@ApiImplicitParam(name = "id", value = "主键ID", required = true, paramType = "query"),
})
- @ApiModel(value = “User”,description = “用户实体”) 标注于实体类
- @ApiModelProperty(value = “主键”,name = “id”) 标注与实体类的属性
- @ApiOperationSupport(author = “lsx”,order = 1) 标注方法上 添加作者 接口排序（Knife4j增强注解：需要在application.yml中开启增强功能）
示例代码
@RestController
@RequestMapping(value = "/swagger",method = RequestMethod.POST)
@Api(tags = "swaggerController")
public class SwaggerController {
@RequestMapping("/demo1")
@ApiOperation("写注释我是认真的")
@ApiOperationSupport(author = "lsx",order = 1)
@ApiImplicitParams({
@ApiImplicitParam(name = "username", value = "用户名", required = true,paramType = "query"),
@ApiImplicitParam(name = "password", value = "密码", required = true, paramType = "query"),
@ApiImplicitParam(name = "createTime", value = "创建时间", required = true, paramType = "query"),
})
public SwaggerTestEntity demo1(@ApiIgnore SwaggerTestEntity user,@ApiParam(name = "videoFile",value = "文件上传") MultipartFile videoFile) {
SwaggerTestEntity userEntity = new SwaggerTestEntity()
.setCrateTime(new Date())
.setId("uuid")
.setUsername(user.getUsername())
.setPassword(user.getPassword());
return userEntity;
}
}
@Data
@Accessors(chain = true)
@ApiModel(value = "SwaggerTestEntity",description = "swagger测试实体")
public class SwaggerTestEntity implements Serializable{
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "主键",name = "id")
private String id;
@ApiModelProperty(value = "用户名",name = "username")
private String username;
@ApiModelProperty(value = "密码",name = "password")
private String password;
@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
@JsonFormat(pattern="yyyy-MM-dd HH:mm:ss",timezone = "GMT+8")
@ApiModelProperty(value = "创建日期",name = "crateTime")
private Date crateTime;
}
接口界面
@RequestMapping("/demo2")
@ApiOperation("动态请求参数和动态响应参数")
@ApiOperationSupport(author = "lsx",order = 2)
@DynamicParameters(name = "",properties = {
@DynamicParameter(name = "phone",value = "手机号"),
@DynamicParameter(name = "code",value = "验证码"),
@DynamicParameter(name = "age",value = "年龄"),
@DynamicParameter(name = "sex",value = "性别"),
})
@DynamicResponseParameters(name = "json",properties = {
@DynamicParameter(name = "phone",value = "手机号"),
@DynamicParameter(name = "code",value = "验证码"),
@DynamicParameter(name = "age",value = "年龄"),
@DynamicParameter(name = "sex",value = "性别"),
})
public JSONObject demo2(@RequestBody Map<String, Object> params) {
Object phone = params.get("phone");
Object name = params.get("name");
Object age = params.get("age");
Object sex = params.get("sex");
JSONObject json = new JSONObject();
json.put("phone", phone);
json.put("name", name);
json.put("age", age);
json.put("sex", sex);
return json;
}
