使⽤knife4j后，终于放弃了swagger-ui
介绍
knife4j是为Java MVC框架集成Swagger⽣成Api⽂档的增强解决⽅案，前⾝是swagger-bootstrap-ui，取名kni4j是希望它能像⼀把⼔⾸⼀样⼩巧，轻量，并且功能强悍!curl是什么命令
knife4j的前⾝是swagger-bootstrap-ui，为了契合微服务的架构发展，由于原来swagger-bootstrap-ui采⽤的是后端Java代码+前端Ui混合打包的⽅式，在微服务架构下显的很臃肿，因此项⽬正式更名为knife4j。
⽬前项⽬主要的模块如下：
此⽰例根据官⽅⽂档介绍演⽰。
开源仓库
Github
码云
核⼼功能
该UI增强包主要包括两⼤核⼼功能：⽂档说明 和 在线调试
⽂档说明：根据Swagger的规范说明，详细列出接⼝⽂档的说明，包括接⼝地址、类型、请求⽰例、请求参数、响应⽰例、响应参数、响应码等信息，使⽤swagger-bootstrap-ui能根据该⽂档说明，对该接⼝的使⽤情况⼀⽬了然。
在线调试：提供在线接⼝联调的强⼤功能，⾃动解析当前接⼝参数，同时包含表单验证，调⽤参数可返回接⼝响应内容、headers、Curl 请求命令实例、响应时间、响应状态码等信息，帮助开发者在线调试，⽽不必通过其他测试⼯具测试接⼝是否正确，简介、强⼤。
UI增强
同时，swagger-bootstrap-ui在满⾜以上功能的同时，还提供了⽂档的增强功能，这些功能是官⽅swagger-ui所没有的，每⼀个增强的功能都是贴合实际，考虑到开发者的实际开发需要，是⽐不可少的功能，主要包括：
个性化配置：通过个性化ui配置项，可⾃定义UI的相关显⽰信息
离线⽂档：根据标准规范，⽣成的在线markdown离线⽂档，开发者可以进⾏拷贝⽣成markdown接⼝⽂档，通过其他第三⽅markdown转换⼯具转换成html或pdf，这样也可以放弃swagger2markdown组件
接⼝排序：⾃1.8.5后，ui⽀持了接⼝排序功能，例如⼀个注册功能主要包含了多个步骤，可以根据swagger-bootstrap-ui提供的接⼝排序规则实现接⼝的排序，step化接⼝操作，⽅便其他开发者进⾏接⼝对接
功能预览
在线预览
快速开始
相信使⽤过springboot的⼈⼤都知道和⽤过swagger，knife4j的使⽤⽅法和swagger⼏乎⼀模⼀样，没有什么学习成本，不同的是展⽰的接⼝UI⽂档更加友好和⼈性化。下⾯开始演⽰⼀个集成项⽬，⾸先来看pom⽂件依赖：
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>1.9.6</version>
</dependency>
只引⼊⼀个knife4j的starter即可，不⽤其它依赖。springboot的配置⽂件和启动类不⽤做任何特殊配置，使⽤knife4j需要⼀个swagger 的配置类，这个配置类和以前使⽤swagger⼏乎是⼀样的：
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUi
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.useDefaultResponseMessages(false)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("spring.ller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("项⽬接⼝⽂档")
.description("服务相关接⼝")
.contact(new Contact("vincent",null,"vincent549@vip.qq"))
.version("1.0")
.build();
}
}
可以看到，内容上没什么变化，唯⼀的变化是类注解需要⽐原来的swagger多加⼀个 @EnableSwaggerBootstrapUi。这样knife4j的所有配置都完成了，启动项⽬可以访问地址：
来看⼀下效果：
接⼝配置
下⾯来配置⼀个简单的接⼝，查看⽂档的展⽰效果。
⾸先来看接⼝的通⽤返回结果：
@ApiModel("通⽤接⼝返回对象")
@AllArgsConstructor
@NoArgsConstructor
@Data
public class Results<T> {
@ApiModelProperty(required = true,notes = "结果码",example = "200")
private int state;
@ApiModelProperty(required = true,notes = "时间戳",example = "1567425139000")
private long time;
@ApiModelProperty(required = true,notes = "返回信息",example = "SUCCESS")
private String message;
@ApiModelProperty(required = true,notes = "返回数据",example = "{\"name\":\"blues\"}") private T content;
}
@ApiModel("⽤户对象")
@AllArgsConstructor
@NoArgsConstructor
@Data
public class UserVO {
@ApiModelProperty(required = true,notes = "⽤户名",example = "blues")
private String name;
@ApiModelProperty(required = true,notes = "⽤户返回消息",example = "hello world")
private String words;
}
通过上⾯两个的定义，接⼝的返回类型就搞定了，下⾯来看接⼝：
@Api(tags = "HELLO CONTROLLER 测试功能接⼝")
@RestController
public class HelloController {
@ApiImplicitParams({
@ApiImplicitParam(name = "name",value = "⽤户名称",required = true,dataType = "String",paramType = "path",example = "blues")
})
@ApiResponses(value = {
@ApiResponse(code = 200, message = "接⼝返回成功状态"),
@ApiResponse(code = 500, message = "接⼝返回未知错误，请联系开发⼈员调试")
})
@ApiOperation(value = "Hello 测试接⼝", notes = "访问此接⼝，返回hello语句，测试接⼝")
@GetMapping("hello/{name}")
public Results<UserVO> hello(@PathVariable String name){
UserVO userVO = new UserVO(name,"hello " + name);
Results<UserVO> results = new Results<>(200,"SUCCESS", userVO);
return results;
}
}
这个接⼝类中分为⼏个部分需要注意，第⼀是类上⾯的@Api注解，描述了整个类的接⼝分类含义。还有⼀个是每个接⼝上⾯的
@ApiImplicitParams 注解，定义了接⼝的所有参数。还有@ApiResponses注解，定义了返回时，所有状态码所代表的的含义，最后是@ApiOperation注解，描述了单个接⼝本⾝的功能。
定义接⼝完成后，我们来重启项⽬，查看⽂档的效果：
⾸页上⾯有⼀些变化，左侧列表多了HelloController类的整体描述栏⽬，我们点开这个栏⽬，可以看到类中定义的所有接⼝：
点击这个接⼝，看到右侧⾮常详细的接⼝⽂档：
上图中展⽰的是接⼝地址，接⼝类型，接⼝描述和详细的⼊参描述，下⾯的相应状态展⽰了我们定义的两种状态类型，还有接⼝的回参也⾮常详细的列了出来：
版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。
发表评论