Swagger详解
- 学习目标 ：
- 了解Swagger的作用和概念
- 了解前后端分离
- 在SpringBoot中集成Swagger
- Swagger简介
- 前后端分离
Vue+SpringBoot
- 后端时代：
前端只用管理静态页面–HTML ==> 后端 --模板引擎JSP =>后端是主力
-
前后端分离时代：
- 后端：后端控制层、服务层、数据访问层 【后端团队】
- 前端：前端控制层、视图层 【前端团队】
- 伪造后端数据，json，已经存在了，不需要后端，前端依旧可以跑起来；但是要给后端交流，给后端一个格式，让后端传数据
-
前后端如何交互？ ===>API
-
前后端相对独立，松耦合；
-
前后端甚至可以部署在不同的服务器上；
产生一个问题：
- 前后端集成联调，前端人员和后端人员无法做到“及时协商，尽早解决”，最终导致问题集中爆发
解决方案：
- 首先指定一个schema（计划的提纲），实时更新最新API，降低集成的风险
- 早些年：指定word计划文档；
- 现在，前后端分离：
- 前端测试后端接口：postman 早些年用
- 后端提供接口，需要实时更新最新的消息及改动！
- Swagger-----“号称世界上最流行的API框架”
- RestFul Api 文档在线自动生成工具==>Api文档与API定义同步更新
- 直接运行，可以在线测试API接口
- 支持多种语言：Java，php
- 官网：https://swagger.io/
- 在项目中使用Swagger
- 需要springfox 依赖
- swagger2
- ui
- SpringBoot集成Swagger
-
新建一个springbot项目
-
导入相关依赖
<!-- 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.0也可以直接用启动器，springboot
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
ps：最好用上面两个依赖，启动器整合的可能会出现bug
- 配置swagger–config
package com.qian.swagger.config;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
}
- 写一个controller，测试
package com.qian.swagger.controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController //返回字符串
public class HelloController {
@RequestMapping(value = "/hello")
public String hello(){
return "hello";
}
}
-
进入http://localhost:8080/swagger-ui.html 进入swagger
- 如果进入不了，则将依赖降级，例如降到2.9.2，可以成功进入
-
因为版本问题启动报错，可以在配置文件上加上
- spring.mvc.pathmatch.matching-strategy=ant_path_matcher
- 配置swagger
- Swagger的bean实例 Docket
package com.qian.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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 javax.xml.bind.annotation.XmlType;
import java.util.ArrayList;
@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("xqh","https://blog.csdn.net/m0_56116754?spm=1000.2115.3001.5343","791172229@qq.com");
return new ApiInfo(
"我的SwaggerApi文档",
"即使最小的帆也能远航",
"1.0",
"https://blog.csdn.net/m0_56116754?spm=1000.2115.3001.5343",
contact,
"Apache 2.0",
"http://apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
- Swagger配置扫描接口
Docket.select()
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors 配置要扫描的接口的方法
//basePackage:指定要扫描的包
//any（）：扫描全部
//none（）：都不扫描
//withClassAnnotation :扫描类上的注解
//withMethodAnnotation:扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.qian.swagger.controller"))
//过滤什么路径
//ant（）:只扫描
//any（）：过滤全部
//none（）：都不过滤
.paths(PathSelectors.none())
.build();
}
配置是否启动swagger
.enable(false) //不能使用swagger
😱 Could not render e, see the console.
- 题目：我只希望我的swagger在生产环境中使用，在发布的时候不使用，该怎么做？
- 判断是不是生产环境
- 注入enable（）
1）判断生产环境
//设置要显示的Swagger环境
Profiles profiles=Profiles.of("dev","test");
//获取项目环境：通过environment.acceptsProfiles判断是否处在自己设定的环境当中
boolean flag = environment.acceptsProfiles(profiles);
//系统检测到是dev环境或者test环境，就可以启动swagger
2）多环境配置
applicatin-dev.properties
server.port=8081
application-test.properties
server.port=8082
application.properties
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
spring.profiles.active=dev
//启用的是dev环境，之前设置的是检测到dev环境就可以启动swagger，所以进入http://localhost:8080/swagger-ui.html 可以进入swagger 。这样就能实现只在生产环境启动swagger
- 配置API文档的分组
.groupName("xqh")
配置多个分组
@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 给实体类加上注释
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String pwd;
}
@Api(tags = “控制器”)给控制类加注释
@ApiOperation 给方法加注释
@ApiParam给参数加注释
package com.qian.swagger.controller;
import com.qian.swagger.pojo.User;
import io.swagger.annotations.Api;
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;
@Api(tags = "控制器")
@RestController //返回字符串
public class HelloController {
@GetMapping(value = "/hello")
public String hello(){
return "hello";
}
//只要我们的接口中，返回值中存在实体类，就会被扫描到swagger中
@PostMapping(value = "/user")
public User user(){
return new User();
}
//Operation接口，不是放在类上，是方法。给方法加上注释
@ApiOperation("hello2控制")
@GetMapping("/hello2")
public String hello2(@ApiParam("用户名") String username){
return "hello"+username;
}
}
- 总结
- 我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息
- 接口文档实时更新
- 可以在线测试
- 前后端有效交流
Swagger是一个优秀的工具，几乎所有大公司都有使用它。
注意点：
在正式发布的时候，关闭Swagger！出于安全考虑，并且节省运行的内存。
1万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
