一、Swagger2
介绍:
- 号称世界上最流行的Api框架;
- RestFul Api文档在线自动生成工具=》Api文档与API定义同步更新;
- 直接运行,可以在线测试API接口;
- 支持多种语言:Java,Php...
SpringBoot集成Swagger2
在项目中使用Swagger需要Springbox(1、swagger2;2、ui )
1、在maven(官网:https://mvnrepository.com/)中查找相关依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2、配置Swagger ==> SwaggerConfig
@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {
}
3、运行测试,访问路径 :http://localhost:8080/swagger-ui.html
运行报错 “ Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException ”
原因:版本问题。springboot高版本(2.6.x)和swagger2的低版本(2.9.2)不兼容,将springboot改为低版本如2.1.x,2.4.x等
4、配置swagger信息
//配置Swagger的Docket的bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
//配置swagger信息=apiInfo
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("Sugar","https://swagger.io/","3499832640@qq.com");
return new ApiInfo(
"Swagger学习笔记",
"Study!!!!!!!!!",
"v1.0",
"https://swagger.io/",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
5、swagger配置扫描接口
//配置Swagger的Docket的bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//enable:是否启动swagger,默认为true,即启动
.enable(false)
.select()
//RequestHandlerSelectors:配置要扫描接口的方式
//basePackage:指定要扫描的包
//any():扫描全部
//none():不扫描
//withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象
//withMethodAnnotation:扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
//paths():过滤什么路径
.paths(PathSelectors.ant("/kuang/**"))
.build()
;
}
Swagger在生产环境中使用,在发布时不使用?
- 判断是否是生产环境 flag=false
- 注入enable(flag)
//设置要显示的swagger环境
Profiles profiles=Profiles.of("dev","test");
//通过environment.acceptsProfiles判断是否处在自己设定的环境中
boolean flag=environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag)
.select()
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
//paths():过滤什么路径
.paths(PathSelectors.ant("/kuang/**"))
.build()
;
}
6、配置API文档的分组
.groupName("Form")
如何配置多个分组;多个Docket实例即可
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}
总结:
我们可以通过Swagger给一些比较难理解的属性或接口,增加注释信息
接口文档实时更新
可以在线测试
【注意点】在正式发布的时候,一定要关闭Swagger!!!处于安全以及节省内存的考虑!
二、Knife4j (推荐)
Knife4j是一款可以提供在线API文档的框架,是基于Swagger2框架实现的。
框架适配
- Spring MVC
- Spring Boot 2.2、2.3、2.4、2.5、2.6、2.7
SpringBoot集成knife4j
1、导入依赖
<!--引入Knife4j的官方start包-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<!--使用Swagger2-->
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.9</version>
</dependency>
2、配置Knife4j==> Knife4jConfig
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {
@Bean(value = "dockerBean")
public Docket dockerBean() {
//指定使用Swagger2规范
Docket docket=new Docket(DocumentationType.SWAGGER_2)
.apiInfo(new ApiInfoBuilder()
//描述字段支持Markdown语法
.description("# Knife4j RESTful APIs")
.termsOfServiceUrl("https://doc.xiaominfo.com/")
.contact("xiaoymin@foxmail.com")
.version("1.0")
.build())
//分组名称
.groupName("用户服务")
.select()
//这里指定Controller扫描包路径
.apis(RequestHandlerSelectors.basePackage("com.github.xiaoymin.knife4j.controller"))
.paths(PathSelectors.any())
.build();
return docket;
}
}
3、接口测试
@Api("测试")
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello(){
return "hello";
}
@PostMapping("/user")
public User user(){
return new User();
}
@ApiImplicitParam(name = "name",value = "姓名",required = true)
@ApiOperation(value = "向客人问好")
@GetMapping("/sayHi")
public ResponseEntity<String> sayHi(@RequestParam(value = "name")String name){
return ResponseEntity.ok("Hi:"+name);
}
}
4、访问路径
默认:http://localhost:8080/doc.html
版本说明:
Knife4j 2.0.6及以上的版本兼容SpringBoot大于等于2.2.x
(2.6.0之后的需要设置
spring.mvc.pathmatch.matching-strategy =ant-path-matcher
)
三、Postman
官网下载地址:https://www.postman.com/downloads/
ps: 图片来源 接口测试之Postman使用全图文指南