Swagger
2021年10月13日大约 3 分钟约 794 字
本篇笔记写得不好,但似乎也没有必要......
一个比较好的介绍参考:Swagger 入门教程-慕课网 (imooc.com)
1. 背景:前后端分离
在后端时代,前端只用管理静态页面。
- HTML -> 后端
- 模板引擎、JSP -> 后端是主力
前后端分离时代:
- 后端:后端控制层、服务层、数据访问层,后端团队
- 前端:前端控制层、视图层,前端团队
- 前端通过伪造后端数据(json),能够不需要后端即将整个前端工程运行起来
- 前后端相对独立、松耦合,甚至可以部署在不同的服务器上
那么在前后端分离时代前后端如何进行交互?答案是 API。
Swagger 号称世界上最流行的 API 框架,其有如下特点:
- RestFul Api 文档在线自动生成,因而 Api 文档与 Api 定义是同步更新的
- 直接运行,可以在线测试 Api 接口
- 支持多种语言(Java, Php, ...)
2. Swagger 简介及使用步骤
官网:https://swagger.io/ 。
Maven 坐标:有两个,分别是springfox-swagger2
, springfox-swagger-ui
。
快速入门——SpringBoot 集成 Swagger:
新建一个 SpringBoot Web 项目
导入相关依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
编写一个 Hello 工程
配置 Swagger:通过 Config 配置类
/** * 配置一些介绍信息。 */ @Configuration @EnableSwagger2 public class SwaggerConfig { // 配置了 Swagger 的 Docket 的 bean 实例 @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()); } // 配置 Swagger 信息 private ApiInfo apiInfo() { // 作者信息 Contact contact = new Contact("徐川", "https://chua-n.com/", "chua_n@qq.com"); return new ApiInfo( "荒流的 SwaggerAPI 文档", "合抱之木,生于毫末", "v1.0", "https://chua-n.com/", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList() ); } }
只要 Swagger 扫描包下接口的返回值中存在实体类,它就会被生成到 Swagger Api 文档中:
@PostMapping(value = "/user")
public User user() {
return new User();
}
@ApiOperation("Post 测试类") // Swagger 注解
@PostMapping(value = "/post")
public User post(@ApiParam("用户名") User user) { // Swagger 注解
// ...
reutnr user;
}
在实际使用时,通过 Swagger 给一些比较难理解的属性/接口增加注释信息,生产的接口文档可以实时更新,并且在线测试。
3. Swagger 配置
3.1 配置要扫描的接口
@Configuration
@EnableSwagger2
public class SwaggerConfig {
// 配置了 Swagger 的 Docket 的 bean 实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()).select()
// RequestHandlerSelectors:配置要扫描接口的方式
// basePackage: 指定要扫描的包
// any(): 扫描全部
// none(): 不扫描
// withClassAnnotation: 扫描类上的注解,参数是一个注解的反射对象
// withMethodAnnotation: 扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.chuan.swagger.controller"))
// paths(...):过滤什么路径
.paths(PathSelectors.ant("/chuan/**"))
.build();
}
private ApiInfo apiInfo(){
// ...
}
}
3.2 配置 Swagger 只在开发环境生效
@Configuration
@EnableSwagger2
public class SwaggerConfig {
// 配置了 Swagger 的 Docket 的 bean 实例
@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) // 为 false 时不生成 SwaggerApi 文档
.select()
.apis(RequestHandlerSelectors.basePackage("com.chuan.swagger.controller"))
.build();
}
private ApiInfo apiInfo(){
// ...
}
}