学习目标:
了解Swagger的作用和概念了解前后端分离在SpringBoot中集成Swagger
Swagger简介
前后端分离(主流)
Vue + SpringBoot
后端时代:前端只用管理静态页面;html==>后端。模板引擎==>JSP,后端是主力
前后端分离时代:
后端:后端控制层(controller),服务层(service),数据访问层(dao)【后端团队】前端:模型层(model),前端控制层(view-model),视图层(view)【前端团队】 伪造后端数据(通过过json模拟),不需要后端传递,前端可以模拟运行 前后端如何交互? 通过API前后端相对独立,松耦合;前后端甚至可以部署在不同的服务器上
产生一个问题:
前后端集成联调,前端人员和后端人员无法做到”即使协商,尽早解决“,最终导致问题集中爆发
解决方案:
首先指定schema[计划的提纲],实时更新最新API,降低集成的风险早先年:制定Word计划档案;前后端分离: 前端测试后端接口:postman后端提供接口,需要实时更新最新的消息及改动
Swagger
号称世界上最流行的Api框架RestFul API 文档在线自动生成工具(API文档与API定义同步更新)直接运行,可以在线测试API接口支持多种语言:Java、PHP。。。官网:https://swagger.io/
在项目使用Swagger需要Springbox
swagger
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency>
ui
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency>
SpringBoot集成Swagger
新建一个SpringBoot web项目
导入相关依赖(swagger2、ui)
新建一个HelloController测试工程是否正确
配置Swagger,新建一个config目录,在目录中编写SwaggerConfig文件。
@Configuration@EnableSwagger2public class SwaggerConfig {}
++ps.目前Swagger已经可以运行,以后的一些Swagger配置就写在这里。++
测试运行:http://localhost:8080/swagger-ui.html
配置Swagger信息
Swagger的bean实例Docket
//配置swagger信息apiInfoprivate ApiInfo apiInfo(){//作者信息Contact contact = new Contact("倪先森", "这里是url", "这里是邮箱");return new ApiInfo("nxs的Swagger的API文档","即使再小的帆也能远航","1.0","urn:tos",contact,"Apache 2.0","/licenses/LICENSE-2.0",new ArrayList());}
Swagger配置扫描接口
Docket.select()
@Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("club.nxs.swagger.controller"))//RequestHandlerSelectors配置要扫描的方式//.basePackage() 指定要扫描的包//.any() 扫描全部//.none() 全部都不扫描//withClassAnnotation: 扫描类上的注解,参数是注解的反射对象(ResController.class)//withMethodAnnotation: 扫描方法上的注解(RequestMapping.class)//.paths(PathSelectors.ant("/nxs/**"))//paths():过滤什么路径.build();}
如何让Swagger在生产环境中使用,在发布的时候不适用?
判断是不是生产环境 flag = false注入enable(flag)
@Beanpublic Docket docket(Environment environment){//设置要显示的Swagger环境Profiles profile = Profiles.of("dev","test");//environment.acceptsProfiles 判断是否处在自己设定的环境中boolean flag = environment.acceptsProfiles(profile);return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(flag) //默认true,是否启用Swagger, 如果是false,Swagger则不会再浏览器显示.select().apis(RequestHandlerSelectors.basePackage("club.nxs.swagger.controller"))//.paths(PathSelectors.ant("/nxs/**")).build();}
配置文档的分组
.groupName("nxs")
ps:如何配置多个分组?多个Docket实例即可
@Beanpublic Docket docket1(Environment environment){return new Docket(DocumentationType.SWAGGER_2).groupName("A");}@Beanpublic Docket docket2(Environment environment){return new Docket(DocumentationType.SWAGGER_2).groupName("B");}@Beanpublic Docket docket3(Environment environment){return new Docket(DocumentationType.SWAGGER_2).groupName("C");}
实体类配置:
//只要我们的接口中,返回值存在实体类,它就会被扫描到Swagger@ApiModel("用户实体类") //就是给生成文档加上注释 == @Api("注释")public class User{@ApiModelProperty("用户名")public String username;}.................................................@ResControllerpublic class HelloController{@ApiOperation("Hello")@PostMapping(value="/user")public User user(){return new User();}public class hello2(@ApiParam("用户名") String username){return "hello";}}
总结
我们可以通过Swagger给一些比较难理解的属性或者接口,增加注释信息接口文档实时更新可以在线测试【注意点】在正式发布的时候,关闭Swagger!!!,出于安全考虑,而且节省内存
备注:导入包
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.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;