Swagger
学习目标:
- 了解Swagger的作用和概念
- 了解前后端分离
- 在SpringBoot中集成Swagger
swagger简介
-
号称世界上最流行的api框架
-
RestFul API文档在线自动生成工具=》API文档与Api定义同步更新
-
直接运行,可以在线测试Api接口
在项目使用Swagger需要springfox
swagger2
ui
SpringBoot集成Swagger
-
新建一个springBoot——web项目
-
导入相关依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.10.5</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.10.5</version> </dependency>
-
编写一个Hello工程
-
配置Swagger------->Config
@Configuration @EnableSwagger2WebMvc //开启Swagger2 public class SwaggerConfig { }
配置swagger
Swagger的bean实例Docker
//配置了swagger的Docket的bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
}
//配置swagger信息的ApiInfo
private ApiInfo apiInfo() {
Contact contact = new Contact("林森", "https://www.cnblogs.com/mjjh/", "1962521583@qq.com");
return new ApiInfo(
"Api Documentation",
"Api Documentation",
"1.0",
"urn:tos",
contact, "Apache 2.0",
"https://www.cnblogs.com/mjjh/",
new ArrayList<VendorExtension>());
}
配置扫描接口
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
/**
*RequestHandlerSelectors配置要扫描接口的方式
basePackage指定扫描包 最常用的
any()扫描全部
none()扫描都不扫描
withClassAnnotation(RestController.class)扫描类上的注解,参数是一个注解的反射对象
withMethodAnnotation(GetMapping.class)扫描方法上的注解
*/
.apis(RequestHandlerSelectors.basePackage("com.mjh.controller"))
//paths()过滤扫什么路径
.paths(PathSelectors.ant("/mjh/**"))
.build();
}
配置是否启动Swagger
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false) //是否启动Swagger,如果为false,则Swagger不能再浏览器中使用
.select()
.apis(RequestHandlerSelectors.basePackage("com.mjh.controller"))
.build();
}
只希望我的Swagger在生产环境中使用,在发布的时候不使用?
-
判断是不是生产环境 flag=false
-
注入enable(flag)
application.properties spring.profiles.active=dev
application-dev.yml server: port: 8081
application-pro.yml server: port: 8082
//配置了swagger的Docket的bean实例 @Bean public Docket docket(Environment environment){ //设置要显示的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.mjh.controller")) .build(); }
配置Api文档的分组
.groupName("日志")
如何配置对个分组(多个Docket实例即可)
@Bean
public Docket docket1(Environment environment){
return new Docket(DocumentationType.SWAGGER_2).groupName("笔记");
}
@Bean
public Docket docket2(Environment environment){
return new Docket(DocumentationType.SWAGGER_2).groupName("随笔");
}
@Bean
public Docket docket3(Environment environment){
return new Docket(DocumentationType.SWAGGER_2).groupName("首页");
}
实体类配置
注释就是为了给swagger说明
//@Api(注释)等价于
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
public String name;
@ApiModelProperty("电话")
public String phone;
}
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello(){
return "helloo";
}
/**
* 只要我们的接口中,返回值中存在实体类,就会被扫描到Swagger中
* @return
*/
@PostMapping("/user")
public User user(){
return new User();
}
//ApiOperation接口 放在方法上
@ApiOperation("Hello控制类")
@PostMapping("/hello1")
public String hello1(@ApiParam("用户名") String name){
return "Hello"+name;
}
}
- 我们可以通过Swagger给一些比较难理解的属性或者接口,增加注释信息
- 接口文档实时更新
- 可以在线测试
注意:出于安全考虑,在正式发布的时候要关闭Swagger