Swagger UI简介
Swagger UI 简介
Swagger UI允许任何人（无论您是开发团队还是最终用户）都可以可视化API资源并与之交互，而无需任何实现逻辑。它是根据您的OpenAPI（以前称为Swagger）规范自动生成的，具有可视化文档，可简化后端实现和客户端使用。
SwaggerUI 特点
- 无依赖 UI可以在任何开发环境中使用，无论是本地还是在Web端中。
- 人性化 允许最终开发人员轻松地进行交互，并尝试API公开的每个操作，以方便使用。
- 易于浏览 归类整齐的文档可快速查找并使用资源和端点。
- 所有浏览器支持 Swagger UI 在所有主要浏览器中均可使用，以适应各种可能的情况。
- 完全可定制 通过完整的源代码访问方式以所需方式设置和调整Swagger UI。
- 完整的OAS支持 可视化Swagger 2.0或OAS 3.0中定义的API。
前后端分离
Vue + SpringBoot
后端时代：前端只用管理静态页面; html==》后端。 模版引擎 JSP=>后端是主力
前后端分离时代：
- 后端：后端控制层、服务层、数据访问层 【后端团队】
- 前端：前端控制层、视图层 【前端团队】
- 伪造后端数据，json。在后端开发前数据以及存在，不需要后端，前端工程师依旧能将项目跑起来。
- 前后端如何交互？ ==>API
- 前后端相对独立，松耦合；
- 前后端甚至可以部署在不同的服务器上。
产生一个问题
- 前后端集成联调，前端人员和后端人员无法做到 “及时协商，尽早解决”，最终导致问题集中爆发；
解决方案：
- 首先指定schema[计划的提纲]，实时更新最新的API，降低集成的风险。
- 早些年，制定Word计划文档
- 前后端分离：
- 前端测试后端接口使用：Postman工具。
- 后端提供接口：需要实时更新最新改动和消息。
Swagger登场
- 号称世界上最流行的API框架。
- Restful API文档在线自动生成工具 API文档与API定义同步更新。
- 直接运行，可以在线测试API接口。
- 支持多种语言 如：Java 、PHP…
官网
https://swagger.io/
在项目只能使用SwaggerUI
需要使用Springfox,配置的组件有
- Swagger 2
- UI 显示页面
springboot集成Swagger
1.idea新建SpringBoot-Web工程
2.POM文件中导入springfox-swagger2和springfox-swagger-ui
dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger-uiartifactId>
<version>2.9.2version>
dependency>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger2artifactId>
<version>2.9.2version>
dependency>
在这里插入代码片
3.编写一个测试Controller 测试SpringBoot工程搭建是否成功。
4.配置Swagger 编写Config文件
- 新建一个名为config的Package包
- 创建SwaggerConfig配置类
- @Configuration 表明这是一个配置类
- @EnableSwagger2 开启Swagger2
@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {
}
5 、测试运行
浏览器打开 http://localhost:8080/swagger-ui.html
Swagger配置扫描接口
- 配置接口扫描与作者信息
使用Dokcet对象中的 .select()方法
/**
* 配置了Swagger 的Docket的bean实例,扫描接口的位置
* .apis
* RequestHandlerSelectors 配置swagger扫描接口的方式
* basePackage() 指定要扫描哪些包
* any() 全部都扫描
* none() 全部不扫描
* withClassAnnotation() 扫描类上的注解 参数是一个注解的反射对象
* withMethodAnnotation() 扫描包上的注解
* .paths
* PathSelectors 路径扫描接口
* ant 配置以xxx 开头的路径
* @return
*/
@Bean
public Docket docket( ){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("James")
.select()
.apis(RequestHandlerSelectors.basePackage("com.study.swagger.controller"))
//.paths(PathSelectors.ant("/hello/**"))
.build();//构建者模式
}
/**
* 配置Swagger信息 apiinfo
* @return
*/
private ApiInfo apiInfo(){
//配置作者信息
Contact DEFAULT_CONTACT = new Contact("James", "https://blog.csdn.net/zhanshixiang/", "[email protected]");
return new ApiInfo(
"James 的Swagger API文档",
"码出高效",
"v1.0",
"https://blog.csdn.net/zhanshixiang/",
DEFAULT_CONTACT,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
配置是否自动启动Swagger
在开发环境开启SwaggerUI ，生产环境关闭SwaggerUI 是因为开发环境是内部人员，生产环境是客户。为了程序的安全性需要关闭SwagggerUI
/**
* 配置了Swagger 的Docket的bean实例,扫描接口的位置
* .apis
* RequestHandlerSelectors 配置swagger扫描接口的方式
* basePackage() 指定要扫描哪些包
* any() 全部都扫描
* none() 全部不扫描
* withClassAnnotation() 扫描类上的注解 参数是一个注解的反射对象
* withMethodAnnotation() 扫描包上的注解
* .paths
* PathSelectors 路径扫描接口
* ant 配置以xxx 开头的路径
* @return
*/
@Bean
public Docket docket(Environment environment){
//设置要显示的Swagger 环境
Profiles profiles =Profiles.of("dev","test");
/**
* 通过 environment.acceptsProfiles 返回的boolean值判断是否处在自己所设定的环境中
*/
boolean flag = environment.acceptsProfiles(profiles);
System.out.println(flag);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("James")
//.enable(flag) //enable配置是否自动启动swagger 如果为False则为不启动，浏览器中不能访问Swagger
.select()
.apis(RequestHandlerSelectors.basePackage("com.study.swagger.controller"))
//.paths(PathSelectors.ant("/hello/**"))
.build();//构建者模式
}
/**
* 配置Swagger信息 apiinfo
* @return
*/
private ApiInfo apiInfo(){
//配置作者信息
Contact DEFAULT_CONTACT = new Contact("James", "https://blog.csdn.net/zhanshixiang/", "[email protected]");
return new ApiInfo(
"James 的Swagger API文档",
"码出高效",
"v1.0",
"https://blog.csdn.net/zhanshixiang/",
DEFAULT_CONTACT,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
- 创建三个properties文件
application.properties
# 激活开发环境
spring.profiles.active=dev
application-dev.properties 开发环境
server.port=8082
application-properties 生产环境
server.port=8083
配置API分组
在协同开发时，每个开发人员都拥有一个属于自己的API组
.groupName("test")
问题：如何配置多个分组？
编写多个Docket 设置不同Docket方法名
/**
* 开发A组的接口
* @return
*/
@Bean
public Docket docketA(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("A");
}
/**
* 开发B组的接口
* @return
*/
@Bean
public Docket docketB(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("B");
}
/**
* 开发C组的接口
* @return
*/
@Bean
public Docket docketC(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("C");
}
访问http://localhost:8080/swagger-ui.html
可以看到分组上有新的组了
配置实体类信息
@ApiModel("用户实体类")
public class User implements Serializable {
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
配置接口方法
@Api("Hello控制类")
@RestController
@RequestMapping("hello")
public class HelloController {
@GetMapping(value = "say")
public String hello() {
return "hello ";
}
/**
* 只要接口中,返回值中存在实体类，他就会被扫描到Swagger中
* @return
*/
@PostMapping(value = "/user")
public User user(){
return new User();
}
/**
* ApiOperation接口，不是放在类上的，是方法
* @return
*/
@ApiOperation("hello控制类")
@GetMapping(value = "/hello2")
public String hello2(@ApiParam("用户名") String username){
return "hello"+username;
}
@ApiOperation("Post测试类")
@PostMapping(value = "/post")
public User post(@ApiParam("用户") User user){
return user;
}
}
