Swagger简介及在SpringBoot中使用swagger
首先给出学习的视频传送门：https://www.bilibili.com/video/BV1Y441197Lw
Swagger
学习目标：
-
-
了解前后端分离
-
在SpringBoot中集成Swagger
Swagger简介
前后端分离 主流搭配：Vue + SpringBoot
后端时代： 前端只用管理静态页面；html==>后端。模板引擎 JSP => 后端主力
前后端分离时代：
-
后端：控制层、服务层、数据访问层
-
前端：前端控制层、视图层 （伪造后端数据 ---json）
-
前端如何跑起来？ ====> API
-
前后端相对独立，松耦合
-
前后端甚至可以部署在不同的服务器上；
产生问题：
-
前后端集成联调，前端人员和后端人员无法做到 ”及时协商，今早解决“，最终导致问题集中爆发
解决方案：
-
首先指定 schema [计划提纲] ，实时更新最新API ，降低集成的风险
-
早些年：制定word 计划文档；
-
前后端分离：
-
前端测试后端接口：postman
-
后端提供接口，需要实时更新最新的消息及改动
-
Swagger
-
号称世界上最流行的Api 框架
-
RestFul Api 文档在线自动生成工具 =>Api文档与APi定义同步更新
-
直接运行，可以在线测试Api 接口
-
支持多语言： （java \ php ...）
在项目中使用Swagger需要 导入依赖 springfox-swagger2 、springfox-swagger-ui
-
swagger2
-
ui
SpringBoot集成Swagger
1、新建一个springboot 的 web项目
2、导入相关依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>3.0.0</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>3.0.0</version> </dependency>
3、编写一个Hello的Get 接口
@Configuration @EnableSwagger2 //开启swagger2 public class SwaggerConfig { //配置swagger 的docket的bean实例 @Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()); } //配置swagger信息 =apiInfo private ApiInfo apiInfo(){ //作者信息 Contact contact=new Contact("路上", "http://localhost:8080/hello", "test@qq.com"); return new ApiInfo("路上的Swagger API文档", "描述。。。", "版本1.0", "http://localhost:8080/hello", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); } }
5、测试运行：http://localhost:8080/swagger-ui.html
Swagger配置扫描接口
Docket.select ()
@Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() //RequestHandlerSelectors ,配置要扫描接口的方式 //basePackage ：指定要扫描的包 .apis(RequestHandlerSelectors.basePackage("com.example.swagger2.controller")) //ang :扫描全部 .apis(RequestHandlerSelectors.any()) //none :都不扫描 .apis(RequestHandlerSelectors.none()) //withClassAnnotation :扫描类上的注解 .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)) //withMethodAnnotation :扫描方法上的注解 .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)) //paths() 过滤什么路径 .paths(PathSelectors.ant("/**")) .build(); }
@Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) //是否启用swagger ，如果为false,则swagger不能在浏览器中访问 .enable(true) .select() .paths(PathSelectors.ant("/**")) .build(); }
问题： 怎样设置Swagger在生产环境中使用，在发布的时候不使用？
-
判断是否生产环境 flag=false
-
注入 enable (flag)
1、新建application-dev.properties和application-pro.properties
2、分别在这两个文件中加入server.port=8000和server.port=8080
3、在application.properties中写上spring.profiles.active=dev
4、在docket() 中获取环境是否dev环境
@Bean public Docket docket(Environment env){//加入Environment来获取配置中的东西 //设置要显示的swagger 环境 Profiles profiles=Profiles.of("dev"); //通过environment.acceptsProfiles判断是否在自己设定的环境当中 boolean flag=env.acceptsProfiles(profiles); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .enable(flag) .select() .paths(PathSelectors.ant("/**")) .build(); }
配置APi的分组
.groupName("路上")
如何配置对个分组--->多个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"); }
实体类的注解
@ApiModel("用户实体类 User") //实体类注释
public class User {
@ApiModelProperty("用户名") //实体类字段注释
public String username;
@ApiModelProperty("密码")
public String password;
}
控制类的注解
//Api 接口注释 @Api(tags="hello控制类") @RestController public class HelloController { @GetMapping("/hello") public String hello(){ return "hello,lushang"; } //ApiOperation接口注释 @ApiOperation("hello接口2") @GetMapping("/hello2") public String hello2(@ApiParam("用户名") String username){ return "hello2"; } //只要我们的接口中，返回值中存在实体类，他就会被扫描到 swagger 中 @ApiOperation("post测试") @PostMapping("/user") public User user(@ApiParam("用户名+密码") User user){ return user; } }
总结：
-
我们可以通过Swagger给一些比较难理解的属性或者接口，增加注解信息
-
接口文档实时更新
-
可以在线测试
【注意点】 在正式发布的时候，关闭Swagger~出于安全考虑。而且节省内存
