一文搞懂Swagger,让你明白用了Swagger的好处!!!
前后端分离缺陷了解Swagger之前,需要先知道什么是前后端分离
现在的时代SpringBoot + VUE以前的时代SSM + JSP模板引擎====>后端程序员前后端分离时代通过相关的API接口进行交互前后端相对独立,松耦合前后端可以分别部署在不同的服务器上伪造后端交互数据,json数据已经存在,不需要后端传入json数据了,前端工程已经可以运行后端:后端控制层 + 服务层 + 数据访问层前端:前端控制层 + 视图层前后端如何交互?但这样会产生新问题前后端集成联调,前端和后端开发人员无法做到及时协商,尽早解决问题,就会导致项目延期解决方案:前端测试后端:postMan后端提供接口,需要实时更新最新的消息和改动首先指定schema[计划大纲],团队实时更新最新的API,可以降低集成的风险;早些年:指定world计划文档前后端分离:Swagger简介Swagger官网
号称世界上最流行的API框架RestFul API文档在线生成工具--->>>==API文档与API同步更新==可以直接运行,可以在线测试API接口支持多种语言:(Java,PHP......)官网界面
使用SpringBoot集成Swagger创建SpringBoot-Web项目,导入相关依赖注意事项:
在项目中使用Swagger需要SpringBoxswagger2swaggerui代码语言：javascript代码运行次数：0运行复制
dependency>
dependency>
创建hello程序扩展,一个hello程序有两个请求,一个是SpringBoot项目默认的/error
image-20200611133103333
代码语言：javascript代码运行次数：0运行复制@RestController
public class HelloController {
/**
* 测试Controller
*
* @return
*/
@GetMapping("/hello")
public String hello() {
return "你好呀!!!Swagger";
}
}
配置Swagger,新建SwaggerConfig代码语言：javascript代码运行次数：0运行复制@Configuration // 标识配置类
@EnableSwagger2 // 开启Swagger
public class SwaggerConfig {
}
测试运行唯一地址:http://localhost:8080/swagger-ui.html
首页信息
配置Swagger信息修改SwaagerConfig代码语言：javascript代码运行次数：0运行复制package com.mobai.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 java.util.ArrayList;
/**
* Software：IntelliJ IDEA 2020.1 x64
* Author: MoBai·杰
* Date: 2020/6/11 13:33
* ClassName:SwaggerConfig
* 类描述：Swagger配置类
*/
@Configuration // 标识配置类
@EnableSwagger2 // 开启Swagger
public class SwaggerConfig {
/**
* 配置了Swagger的Docket的Bean实例
*
* @return
*/
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
/**
* 配置Swagger信息
*
* @return
*/
private ApiInfo apiInfo() {
// 配置作者信息
Contact contact = new Contact("墨白",
"https://www.mobaijun.com",
"mobaijun8@163.com");
// 配置API文档标题
return new ApiInfo("框架师Api",
// API文档描述
"Api Documentation",
// API版本号
"1.0",
// 配置URL(公司官网/blog地址)
"https://www.mobaijun.com",
// 作者信息
contact,
// 以下内容默认即可
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
Swagger配置扫描接口Docket.select();
在SawggerConfig配置类完善配置扫描接口的参数代码语言：javascript代码运行次数：0运行复制 /**
* 配置了Swagger的Docket的Bean实例
*
* @return
*/
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 配置扫描接口
.select()
/*
*RequestHandlerSelectors,配置要扫描接口的方式
* 参数说明:
* basePackage:基于包扫描
* class:基于类扫描
* any():扫描全部
* none():全部都不扫描
* withMethodAnnotation:通过方法的注解扫描
* // withMethodAnnotation(GetMapping.class))
* withClassAnnotation:通过类的注解扫描
*/
.apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
// .paths()过滤,不扫描哪些接口
.paths(PathSelectors.any())
.build();
}
配置Swagger启动代码语言：javascript代码运行次数：0运行复制/**
* 配置了Swagger的Docket的Bean实例
*
* @return
*/
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 配置Swagger是否启动,默认:true
.enable(false)
// 配置扫描接口
.select()
.apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
小测试:如果有一个需求,需要你判断在生成环境中使用,在发布的时候不使用
开发思路先判断.enable()是不是等于false注入Enable(flag)实现,添加application-dev.properties生产环境配置和application-pro.properties发布环境配置默认application.properties环境配置添加代码语言：javascript代码运行次数：0运行复制# 开启profiles.active监听,dev测试环境,pro发布环境
spring.profiles.active=dev
生产环境修改端口号代码语言：javascript代码运行次数：0运行复制server.port=8081
发布环境修改端口号代码语言：javascript代码运行次数：0运行复制server.port=8082
SwaggerConfig配置类判断当前环境代码语言：javascript代码运行次数：0运行复制/**
* 配置了Swagger的Docket的Bean实例
*
* @return
*/
@Bean
public Docket docket(Environment environment) {
// 设置要显示的Swagger环境
Profiles profiles = Profiles.of("dev", "test");
// 通过environment.acceptsProfiles();判断自己是否在自己设定换的环境当中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 监听自己设置的环境
.enable(flag)
// 配置扫描接口
.select()
.apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
配置API文档的分组配置多个组,添加.groupName()代码语言：javascript代码运行次数：0运行复制 /**
* 配置了Swagger的Docket的Bean实例
*
* @return
*/
@Bean
public Docket docket(Environment environment) {
// 设置要显示的Swagger环境
Profiles profiles = Profiles.of("dev", "test");
// 通过environment.acceptsProfiles();判断自己是否在自己设定换的环境当中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 配置分组
.groupName("墨白小组")
// 监听自己设置的环境
.enable(flag)
// 配置扫描接口
.select()
.apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
效果image-20200611145705157
配置多个组代码语言：javascript代码运行次数：0运行复制@Configuration // 标识配置类
@EnableSwagger2 // 开启Swagger
public class SwaggerConfig {
/**
* 添加A组
* 每个组各司其职
*
* @return
*/
@Bean
public Docket docket1() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("A");
}
/**
* 添加B组
*
* @return
*/
@Bean
public Docket docket2() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("B");
}
/**
* 添加C组
*
* @return
*/
@Bean
public Docket docket3() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("C");
}
/**
* 配置了Swagger的Docket的Bean实例
*
* @return
*/
@Bean
public Docket docket(Environment environment) {
// 设置要显示的Swagger环境
Profiles profiles = Profiles.of("dev", "test");
// 通过environment.acceptsProfiles();判断自己是否在自己设定换的环境当中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 配置分组
.groupName("墨白小组")
// 监听自己设置的环境
.enable(flag)
// 配置扫描接口
.select()
.apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
效果image-20200611150302823
实体类配置代码语言：javascript代码运行次数：0运行复制@ApiModel("用户实体类") // 添加注释
public class User {
// 添加注释
@ApiModelProperty("年龄")
private Integer age;
@ApiModelProperty("姓名")
private String name;
@ApiModelProperty("账号")
private String username;
@ApiModelProperty("密码")
private String password;
public Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
}
效果效果图
Swagger常用注解@ApiModel("注释"):实体类添加注释@ApiModelProperty("注释"):给实体类属性添加注释@ApiOperation("注释")给接口(Controller)方法添加注释,放在方法上@ApiParam("")给方法的参数添加注释@Api("")给类添加注释controller代码语言：javascript代码运行次数：0运行复制package com.mobai.swagger.controller;
import com.mobai.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.RestController;
/**
* Software：IntelliJ IDEA 2020.1 x64
* Author: MoBai·杰
* Date: 2020/6/11 13:25
* ClassName:HelloController
* 类描述： 测试类
*/
@ApiOperation("")
@RestController
public class HelloController {
/**
* 测试Controller
*
* @return
*/
@GetMapping("/hello")
public String hello() {
return "你好呀!!!Swagger";
}
/**
* 只要我们的接口中,返回值存在实体类,Swagger就会扫描到
*
* @return
*/
@PostMapping("/user")
public User user() {
return new User();
}
@ApiOperation("Post测试类")
@PostMapping(value = "/post")
public User post(@ApiParam("用户对象") User user) {
return user;
}
}
总结添加@Configuration注解,标识配置类添加@EnableSwagger2注解开启SwaggerSwagger2Swagger-ui创建SpringBoot项目,导入Swagger依赖创建Swagger配置类配置Swagger的Docket的Bean实例配置Swagger信息我们可以通过Swagger给一些比较难理解的属性或者接口,增加注释信息接口文档实时更新可以在线测试Swagger是一个优秀的工具,几乎所有的大公司都在用需要注意:正式发布的时候,关闭swagger!!!出于安全考虑,而且节省运行内存!