Swagger：API框架
Swagger简介
-
号称世界上最流行的Api框架;
-
RestFul Api文档在线自动生成工具=>Api文档与API定义同步更新
-
直接运行，可以在线测试API接口;
-
支持多种语言: Java, Php...
Swagger官网: https://swagger.io/
在项目使用Swagger需要springbox;
- swagger2
- ui
SpringBoot集成Swagger
-
新建一个Spring Boot，web项目
-
导入相关依赖
<!--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> -
编写一个HelloController
-
配置Swagger在config包下写配置类SwaggerConfig
@Configuration @EnableSwagger2 //开启Swagger2 public class SwaggerConfig { } -
测试运行：http://localhost:8080/swagger-ui.html
配置Swagger信息
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
//配置了swagger的Docket的bean实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());//把下面配置的swagger信息加进去
}
//配置swagger信息=apiInfo
private ApiInfo apiInfo () {
//作者信息,作者名，路径，邮箱
Contact contact = new Contact("ys", "https://www.cnblogs.com/yu-si", "");
return new ApiInfo(
"ys的SwaggerAPI文档", //标题
"yuansi", //描述
"v1.0", //版本
"urn:tos", //服务组织路径
// DEFAULT_CONTACT
contact, //作者信息
"Apache 2.0", //开源版本号
"http://www.apache.org/licenses/LICENSE-2.0",//开源版本号路径
new ArrayList());
}
}
测试运行：http://localhost:8080/swagger-ui.html的页面
配置扫描接口及开关
配置扫描接口：
.apis(RequestHandlerSelectors.basePackage("com.ys.controller"))一般用这个
//配置了swagger的Docket的bean实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.ys.controller"))
//RequestHandlerSelectors,配置要扫描接口的方式
//basePackage：指定要扫描的包RequestHandlerSelectors.basePackage("com.ys.controller") 一般用这个
//any()：扫描全部RequestHandlerSelectors.any()
//none()：不扫描RequestHandlerSelectors.none()
//withMethodAnnotation:扫描方法上有GetMapping注解 RequestHandlerSelectors.withClassAnnotation(GetMapping.class)
//withClassAnnotation:扫描类上有RestController注解RequestHandlerSelectors.withClassAnnotation(RestController.class)
.build();
}
配置过滤接口：
.paths(PathSelectors.ant("/ys/**"))//只扫描ys下的api接口 一般用这个
//配置了swagger的Docket的bean实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
//paths()过滤路径
.paths(PathSelectors.ant("/ys/**"))//只扫描ys下的api接口 一般用这个
//PathSelectors.none()不过滤
//PathSelectors.any()过滤全部
//PathSelectors.regex()
.build();
}
配置swagger开关：
.enable(true)
//配置了swagger的Docket的bean实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//把下面配置的swagger加进去
.enable(false)//是否启用Swagger,false不能再浏览器访问，默认true.
.select()
//RequestHandlerSelectors,配置要扫描接口的方式
//basePackage：指定要扫描的包RequestHandlerSelectors.basePackage("com.ys.controller") 一般扫描包
.apis(RequestHandlerSelectors.basePackage("com.ys.controller"))
//paths()过滤路径
.paths(PathSelectors.ant("/ys/**"))//只扫描ys下的api接口 一般用这个
.build();
}
swagger配置:
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
//配置了swagger的Docket的bean实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//把下面配置的swagger加进去
.enable(false)//是否启用Swagger,false不能再浏览器访问，默认true.
.select()
//RequestHandlerSelectors,配置要扫描接口的方式
//basePackage：指定要扫描的包RequestHandlerSelectors.basePackage("com.ys.controller") 一般扫描包
//any()：扫描全部RequestHandlerSelectors.any()
//none()：不扫描RequestHandlerSelectors.none()
//withMethodAnnotation:扫描方法上有GetMapping注解 RequestHandlerSelectors.withClassAnnotation(GetMapping.class)
//withClassAnnotation:扫描类上有RestController注解RequestHandlerSelectors.withClassAnnotation(RestController.class)
.apis(RequestHandlerSelectors.basePackage("com.ys.controller"))
//paths()过滤路径
.paths(PathSelectors.ant("/ys/**"))//只扫描ys下的api接口 一般用这个
//PathSelectors.none()不过滤
//PathSelectors.any()过滤全部
//PathSelectors.regex()
.build();
}
//配置swagger信息=apiInfo
private ApiInfo apiInfo () {
//作者信息,作者名，路径，邮箱
Contact contact = new Contact("ys", "https://www.cnblogs.com/yu-si", "");
return new ApiInfo(
"ys的SwaggerAPI文档", //标题
"yuansi", //描述
"v1.0", //版本
"urn:tos", //服务组织路径
// DEFAULT_CONTACT
contact, //作者信息
"Apache 2.0", //开源版本号
"http://www.apache.org/licenses/LICENSE-2.0",//开源版本号路径
new ArrayList());
}
}
Swagger在一个环境使用
我只希望我的Swagger在生产环境中使用，在发布的时候不适用？
三个application.properties文件，不同文件不同端口不同配置和参数
application.properties配置：
激活dev开发环境---spring.profiles.active=dev
激活prod开发环境---spring.profiles.active=prodapplication-dev.properties开发环境配置
application-prod.properties正式环境配置
-
判断是不是生产环境 flag = false
-
注入enable（flag）
-
@Bean public Docket docket(Environment environment){ //这个接口import org.springframework.core.env.Environment; //设置要显示的Swagger环境, // dev则开启Swagger环境,否则不开启,可以放多个Profiles.of("dev","test"); Profiles profiles = Profiles.of("dev"); //获得项目的环境,通过environment.acceptsProfiles判断是否处在自己设定的环境当中 boolean flag = environment.acceptsProfiles(profiles);//监听 //getActiveProfiles();获得一个激活的文件 //getDefaultProfiles();获得一个默认的文件 return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo())//把下面配置的swagger加进去 .enable(flag)//是否启用Swagger,如果是指定的环境则启用Swagger .select() //RequestHandlerSelectors,配置要扫描接口的方式 //basePackage：指定要扫描的包RequestHandlerSelectors.basePackage("com.ys.controller") 一般用这个 .apis(RequestHandlerSelectors.basePackage("com.ys.controller")) //paths()过滤路径 .paths(PathSelectors.ant("/ys/**"))//只扫描ys下的接口 一般用这个 .build(); }
全代码
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
//配置了swagger的Docket的bean实例
@Bean
public Docket docket(Environment environment){ //这个接口import org.springframework.core.env.Environment;
//设置要显示的Swagger环境,
// dev则开启Swagger环境,否则不开启,可以放多个Profiles.of("dev","test");
Profiles profiles = Profiles.of("dev");
//获得项目的环境,通过environment.acceptsProfiles判断是否处在自己设定的环境当中
boolean flag = environment.acceptsProfiles(profiles);//监听
//getActiveProfiles();获得一个激活的文件
//getDefaultProfiles();获得一个默认的文件
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//把下面配置的swagger加进去
.enable(flag)//是否启用Swagger,false不能再浏览器访问，默认true.
.select()
//RequestHandlerSelectors,配置要扫描接口的方式
//basePackage：指定要扫描的包RequestHandlerSelectors.basePackage("com.ys.controller") 一般用这种
//any()：扫描全部RequestHandlerSelectors.any()
//none()：不扫描RequestHandlerSelectors.none()
//withMethodAnnotation:扫描方法上有GetMapping注解RequestHandlerSelectors.withClassAnnotation(GetMapping.class)
//withClassAnnotation:扫描类上有RestController注解RequestHandlerSelectors.withClassAnnotation(RestController.class)
.apis(RequestHandlerSelectors.basePackage("com.ys.controller"))
//paths()过滤路径
.paths(PathSelectors.ant("/ys/**"))//只扫描ys下的接口 一般用这个
//PathSelectors.none()不过滤
//PathSelectors.any()过滤全部
//PathSelectors.regex()
.build();
}
//配置swagger信息=apiInfo
private ApiInfo apiInfo () {
//作者信息,作者名，路径，邮箱
Contact contact = new Contact("ys", "https://www.cnblogs.com/yu-si", "");
return new ApiInfo(
"ys的SwaggerAPI文档", //标题
"yuansi", //描述
"v1.0", //版本
"urn:tos", //服务组织路径
// DEFAULT_CONTACT
contact, //作者信息
"Apache 2.0", //开源版本号
"http://www.apache.org/licenses/LICENSE-2.0",//开源版本号路径
new ArrayList());
}
}
配置API文档分组
.groupName("ys")
如何配置多个分组；多个Docket示例即可
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket4(){
return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}
接口注释
实体类注释
controller层
@RestController
public class HelloController {
//只要我们的接口中，返回值中存在实体类，他就会被扫描到swagger中
@PostMapping(value = "/user")
public User user() {
return new User();
}
}
pojo层
@ApiModel("用户实体类")//swagger实体类Model文档注释
public class User {
@ApiModelProperty("用户名")//swagger字段Model文档注释,private修饰的swagger获取不到
public String username;
@ApiModelProperty("密码")
public String password;
}
swagger页面注释显示
控制层注释
@RestController
public class HelloController {
@GetMapping(value = "/hello")
public String hello() {
return "hello";
}
//operation接口,不是放在类上的，是方法
@ApiOperation("HelloController控制类")
@PostMapping(value = "/hello2")
public String hello2(@ApiParam("用户名") String username) {
return "hello" + username;
}
}
swagger页面注释显示
小结
- 我们可以通过Swagger给一些比较难理解的属性或者接口， 增加注释信息
- 接口文档实时更新
- 可以在线测试
Swagger是一个优秀的工具,几乎所有大公司都有使用它
[注意点]在正式发布的时候，关闭Swagger! ! !出于安全考虑。而且节省运行的内存;