Java框架之swagger学习及使用
Swagger简介
前后端分离
Vue + SpringBoot
后端时代：前端只用管理静态页面；html==> 后端。模板引擎 JSP =>后端是主力
前后端分离式时代：
- 后端 ：后端控制层，服务层，数据访问层 【后端团队】
- 前端 ：前端控制层，视图层 【前端团队】
- 伪造后端数据，json。已经存在了，不需要后端，前端工程依旧能够跑起来
- 前端后如何交互 ? ===> API
- 前后端相对独立，松耦合；
- 前后端甚至可以部署在不同的服务器上；
产生一个问题：
- 前后端集成联调，前端人员和后端人员无法做到 “即使协商， 尽早解决”，最终导致问题集中爆发；
解决方案：
- 首先指定schema[计划的提纲]，实时更新最新API，降低集成的风险；
- 早些年：指定word计划文档；
- 前后端分离：
- 前端测试后端接口：postman
- 后端提供接口，需要实时更新最新的消息及改动！
Swagger特点
- 号称世界上最流行的Api框架；
- RestFul Api 文档在线自动生成工具=>Api文档与API定义同步更新
- 直接运行，可以在线测试API接口；
- 支持多种语言：（Java，Php…）
官网：[https://swagger.io/
SpringBoot 集成Swagger的使用
在项目使用Swagger需要 springbox；
- swagger2
- ui
项目结构
-
新建一个SpringBoot 的web项目
-
导入相关依赖
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2
- 编写一个Hello工程
helloController文件编写：
package com.kuang.swagger.controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.sql.SQLOutput;
@RestController
public class helloController {
@RequestMapping("/hello")
public String hello(){
return "hello";
}
}
- 配置Swagger ==> Config
@Configuration //相当于component
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
}
- 测试运行：http://localhost:8080/swagger-ui.html
配置Swagger信息
package com.kuang.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
// 配置swagger信息
private ApiInfo apiInfo() {
Contact contact = new Contact("小明", "https://blog.csdn.net/yalu_123456", "8718*****@qq.com");
return new ApiInfo("yalu 的api文档",
"感谢现在努力的自己",
"v1.0",
"https://blog.csdn.net/yalu_123456",
contact,
"apache2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
测试结果：
Swagger配置扫描接口
swiggerconfig类：
@Configuration
@EnableSwagger2
public class SwaggerConfig {
// @Bean
// public Docket docket(){
// return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
// }
//配置了Swagger的Docket的bean实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors，配置要扫描接口的方式
//basePackage:指定要扫描的包
//any():扫描全部
//none():不扫描
//withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
//withMethodAnnotation：扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
//paths()。过滤什么路径
.paths(PathSelectors.ant("/kuang/**"))
.build();
}
// 配置swagger信息
private ApiInfo apiInfo() {
Contact contact = new Contact("小明", "https://blog.csdn.net/yalu_123456", "8718*****@qq.com");
return new ApiInfo("yalu 的api文档",
"感谢现在努力的自己",
"v1.0",
"https://blog.csdn.net/yalu_123456",
contact,
"apache2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
测试结果：
这里我们可以看到经过.paths(PathSelectors.ant("/kuang/**"))过滤之后我们无法看到controller相关内容
配置是否启动Swagger
同样修改swaggerconfig类
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false)//enable是否启动Swagger，如果为False，则Swagger不能再浏览器中访问
.select()
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
//.paths(PathSelectors.ant("/kuang/**"))
.build();
}
// 配置swagger信息
private ApiInfo apiInfo() {
Contact contact = new Contact("小明", "https://blog.csdn.net/yalu_123456", "8718*****@qq.com");
return new ApiInfo("yalu 的api文档",
"感谢现在努力的自己",
"v1.0",
"https://blog.csdn.net/yalu_123456",
contact,
"apache2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
.enable(false)//enable是否启动Swagger，如果为False，则Swagger不能再浏览器中访问
测试结果
在特定环境下使用swagger
我只希望我的Swagger在生产环境中使用，在发布的时候不使用？
- 判断是不是生产环境 flag = false
- 注入enable（flag）
同样我们需要修改swagger类：
//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(Environment environment){
//设置要显示的Swagger环境
Profiles profiles = Profiles.of("dev","test");
//通过environment.acceptsProfiles判断是否处在自己设定的环境当中
boolean flag = environment.acceptsProfiles(profiles);
System.out.println(flag);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag)//enable是否启动Swagger，如果为False，则Swagger不能再浏览器中访问
.select()
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
//.paths(PathSelectors.ant("/kuang/**"))
.build();
}
// 配置swagger信息
private ApiInfo apiInfo() {
Contact contact = new Contact("小明", "https://blog.csdn.net/yalu_123456", "8718*****@qq.com");
return new ApiInfo("yalu 的api文档",
"感谢现在努力的自己",
"v1.0",
"https://blog.csdn.net/yalu_123456",
contact,
"apache2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
这里还需要设置增加两个配置文件
application.properties
spring.profiles.active=pdiv
applicaton-devproperties
server.port=8081
application-pro.peoperties
server.port=8082
这里我们需要注意
//设置要显示的Swagger环境
Profiles profiles = Profiles.of(“dev”,“test”);
这里我们设置了两个字段“dev”和“test”,这里只要是application.properties文件中激活的字段都可以使用swagger,不过需要特别注意访问的端口号！！！（容易入坑）
我们现在来测试下：
注意访问端口：8081
配置API文档的分组
只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中
实体类：
package com.kuang.swagger.pojo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
//@Api(注释)
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
controller:
package com.kuang.swagger.controller;
import com.kuang.swagger.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.sql.SQLOutput;
@RestController
public class helloController {
@RequestMapping("/hello")
public String hello(){
return "hello";
}
//只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中
@PostMapping(value = "/user")
public User user(){
return new User();
}
//Operation接口,不是放在类上的，是方法
@ApiOperation("Hello控制类")
@GetMapping(value = "/hello2")
public String hello2(@ApiParam("用户名") String username){
return "hello"+username;
}
@ApiOperation("Post测试类")
@PostMapping(value = "/postt")
public User postt(@ApiParam("用户名") User user){
int i = 5;
return user;
}
}
测试结果：
总结
- 我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息
- 接口文档实时更新
- 可以在线测试
Swagger是一个优秀的工具，几乎所有大公司都有使用它
【注意点】在正式发布的时候，关闭Swagger！！！出于安全考虑。而且节省运行的内存；