Swagger+knife4j易于整合SpringBoot的OpenAPI⽂档⽣成利器
1.Swagger简介
前端和后端的联调离不开API⽂档，⽽⼿动编写API⽂档是⼀项耗时⼜费⼒的操作。Swagger正是基于简化API⽂档的输出的⼀个优秀的开源框架，通过OpenAPI的规范呈现接⼝信息，⽅便的提供测试和联调。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述⽂件，就可以⾃动⽣成接⼝⽂档和客户端服务端代码，做到调⽤端代码、服务端代码以及接⼝⽂档的⼀致性。
官⽅地址：
swagger.io
2.Springboot集成Swagger2及常见配置
第⼀步：添加依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2.9.2的版本是⽤的最多的，具体的可以直接去maven的官⽹去搜索，⼀个使⽤量最多的版本即可。
第⼆步：配置
新建config包，创建SwaggerConfig类
@EnableSwagger2
@Configuration
public class Swagger2Config {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.
select()
//为当前包路径，控制器类包
.apis(RequestHandlerSelectors.basePackage("ller"))
.paths(PathSelectors.any())
.build();
微服务在哪里}
//构建 api⽂档的详细信息函数
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
//页⾯标题
.title("XX平台API接⼝⽂档")
/
/创建⼈
.contact(new Contact("test","",
"XXX@qq"))
//版本号
.version("1.0")
//描述
.description("系统API描述")
.build();
}
这⾥的配置也⽐较简单。这⾥有很多选项供我们去配置。如果我们的项⽬有多个组，只需要创建多个Docket即可。这时候扫描的包换成每个组的包路径。
第三步：controller类中配置
新建⼀个controller包，然后创建HelloController类
@Api("Hello控制类")
@RestController
public class HelloController {
@GetMapping(value ="/user")
public User getUser(){
return new User("愚公要移⼭","123456");
}
@ApiOperation("可以指定参数的API")
@PostMapping("/param")
public String hello2(@ApiParam("⽤户名") String name){
return"hello"+ name;
}
}
这⾥我们可以看出，使⽤注解就可以对这个类、⽅法、字段等等进⾏解释说明。其他的字段还有很多，在使⽤的时候会有相应的提⽰，可以⾃⼰试⼀遍：
3.常⽤注解
@Api 标识⼀个java类型是⽂档类，⽤controller类的类名上
@ApiModel 表⽰⼀个实体类/模型⽂档，⽤在类名上；
@ApiModelProperty 作⽤在属性上，添加属性描述；
@ApiOperation 作⽤在接⼝类的⽅法上，控制⽅法的相关描述；
@ApiImplicitParam 作⽤在接⼝⽅法上，描述单个参数信息，只能作⽤在⽅法上；
@ApiImplicitParams 作⽤在接⼝⽅法上，@ApiImplicitParam参数组；
@ApiParam 作⽤在接⼝⽅法上，描述单个参数信息，属性基本与@ApiImplicitParam⼀样，但可以作⽤在⽅法、参数、属性上；下⾯分别对每个注解的常⽤参数作讲解。
@Api：
value：字符串，对controller类的作⽤描述，代替原来的description（已过时），⼀般⽤此属性；
tags：字符串数组，标签组，同样可以描述controller的作⽤；
@ApiModel
value：字符串，模型的简短别名，使得在⽂档的导航中便于识别；
description：字符串，模型的附加描述；
@ApiOperation
value：字符串，⽅法的功能描述；
tags：字符串数组，标签组，同样可以描述⽅法的作⽤；
response：ClassType，显⽰指出返回的对象类型；在响应⽰例中会显⽰出改对象的字段以及⽰例、描述；
code：响应代码，默认200，⼀般不改；
@ApiModelProperty
value：字符串，字段描述；
required：boolean；指定参数是否必须，默认false；
example：字符串，参数值的⽰例
@ApiImplicitParam
name：字符串，参数名；
value：字符串，参数描述；
defaultValue：字符串，参数默认值；
required：boolean，标识是否必须传值，默认false；
dataType：字符串，参数类型，可以是某个类名，也可以是基本数据类型的引⽤类名，如Integer；
example：字符串，参数值⽰例；
@ApiImplicitParams
value：@ApiImplicitParam类型数组，当⽅法有多个@ApiImplicitParam参数时，需要放到@ApiImplicitParams注解中@ApiParam
name：字符串，参数名；
value：字符串，参数描述；
defaultValue：字符串，设置默认值；
required：boolean，是否必须，默认false；
example：字符串，参数值⽰例；
4.替换swagger-ui，选择款神器—knife4j
⾸先我们来看下界⾯功能的对⽐，swagger-ui界⾯如下：
访问地址:
localhost:8080/swagger-ui
knife4j界⾯如下：
访问地址:
localhost:8080/doc.html
从以上可以看出knife4j界⾯相⽐swagger-ui界⾯更加美观，功能更加全⾯，除了测试相关功能外，还提供了相应的⽂档管理，很⽅便的输出不同格式的API⽂档，极⼤的⽅便了接⼝⽂档的输出。
5.knife4j的使⽤
Knife4j是为Java MVC框架集成Swagger⽣成Api⽂档的增强解决⽅案，前⾝是swagger-bootstrap-ui，取名kni4j是希望她能像⼀把⼔⾸⼀样⼩巧，轻量，并且功能强悍!
Knife4j的前⾝是swagger-bootstrap-ui，为了契合微服务的架构发展，由于原来swagger-bootstrap-ui采⽤的是后端Java代码+前端Ui混合打包的⽅式，在微服务架构下显的很臃肿，因此项⽬正式更名为knife4j
更名后主要专注的⽅⾯
前后端Java代码以及前端Ui模块进⾏分离，在微服务架构下使⽤更加灵活
提供专注于Swagger的增强解决⽅案，不同于只是改善增强前端Ui部分
5.1 项⽬模块
⽬前主要的模块包括：
模块名称说明
knife4j为Java MVC框架集成Swagger的增强解决⽅案
knife4j-admin云端Swagger接⼝⽂档注册管理中⼼，集成gateway⽹关对任意微服务⽂档进⾏组合集成
knife4j-extension chrome浏览器的增强swagger接⼝⽂档ui，快速渲染swagger资源
knife4j-service为swagger服务的⼀系列接⼝服务程序
knife4j-front knife4j-spring-ui的纯前端静态版本,⽤于集成⾮Java语⾔使⽤swagger-bootstrap-ui knife4j的前⾝，最后发布版本是1.9.6
5.2 业务场景
不使⽤增强功能，纯粹换⼀个swagger的前端⽪肤
不使⽤增强功能，纯粹换⼀个swagger的前端⽪肤，这种情况是最简单的，你项⽬结构下⽆需变更
可以直接引⽤swagger-bootstrap-ui的最后⼀个版本1.9.6或者使⽤knife4j-spring-ui
⽼版本引⽤

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。