当前位置：首页 > news >正文

《Spring Boot 集成 Swagger：打造高效接口文档与开发体验》

news 来源：原创 2024/9/22 21:29:13

Swagger

一.导语：

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

二.Swagger是什么？它能干什么？

https://swagger.io/

发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是Swagger的由来。通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。

框架说明

现在SWAGGER官网主要提供了几种开源工具，提供相应的功能。可以通过配置甚至是修改源码以达到你想要的效果。

Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。
**Swagger UI:**提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。
Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
Swagger Inspector: 和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。
Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

PS：
Springfox Swagger: Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的，在这里列出来做个说明，方便后面作一个使用的展开。其实swagger是有两个版本的，区别还挺大的，一个是swagger-ui也就是swagger1，还有一个是springfox-swagger也就是swagger2;

总结：

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。

Springfox-swagger,则可以通过扫描代码去生成这个描述文件，连描述文件都不需要再去维护了。所有的信息，都在代码里面了。代码即接口文档，接口文档即代码。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

作用：

1.接口的文档在线自动生成

2.功能测试

三.SpringBoot集成Swagger

3.1 初始实现步骤

1.添加Maven依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency><dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>

2.编写一个配置类-SwaggerConfig来配置 Swagger@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {
}3.访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；
注意:
如果启动报错空指针是因为springboot2.6.0中将SpringMVC 默认路径匹配策略从AntPathMatcher 
更改为PathPatternParser，导致出错可以在启动类上加上@EnableWebMvc注解或者在配置中切换为
原先的AntPathMatcherspring.mvc.pathmatch.matching-strategy=ant_path_matcher.

3.2 配置Swagger

1.Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swagger
@Bean //配置docket以配置Swagger具体参数
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2);}2.可以通过apiInfo()属性配置文档信息
//配置文档信息
private ApiInfo apiInfo() {
Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
return new ApiInfo("Swagger学习", 
// 标题"学习演示如何配置Swagger", // 描述
"v1.0", // 版本
"http://apesource.com", // 组织链接
contact, // 联系人信息
"Apach 2.0 许可", // 许可
"许可链接", // 许可连接
new ArrayList<>()// 扩展
);
}3.Docket 实例关联上 apiInfo()
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}4.重启项目，访问测试 http://localhost:8080/swagger-ui.html 看下效果；

3.3 配置扫描接口

1.构建Docket时通过select()方法配置怎么扫描接口
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫
描接口
.apis(RequestHandlerSelectors.basePackage("com.apesource.swagger.controller"))
.build();
}2.重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到一个类
3.除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式
any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解
的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口4.除此之外，我们还可以配置接口扫描过滤
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫
描接口
.apis(RequestHandlerSelectors.basePackage("com.apesource.swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/apesource开头的接口
.paths(PathSelectors.ant("/apesource/**"))
.build();
}5.这里的可选值还有
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

3.4 配置API分组

1.如果没有配置分组，默认是default。通过groupName()方法即可配置分组
@Bean
public Docket docket(Environment environment) {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.groupName("hello") // 配置分组
// 省略配置....
}2.重启项目查看分组
3.如何配置多个分组？配置多个分组只需要配置多个docket即可
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

3.5 拓展：其他皮肤

我们可以导入不同的包实现不同的皮肤定义
1.默认的访问 http://localhost:8080/swagger-ui.html
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>2.bootstrap-ui 访问 http://localhost:8080/doc.html
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.1</version>
</dependency>

四.常用注解

swagger通过注解生成接口文档，包括接口名、请求方法、参数、返回信息的等等。
@Api：修饰整个类，描述Controller的作用
语法：@Api(tags="说明该类的作用，可以在UI界面上看到的注解"，value = "/类的访问路径",
description = "类的文字描述")@ApiOperation：描述一个类的一个方法，说明方法的作用
语法：@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回
参数类型”, notes = “接口发布说明”）@ApiImplicitParam：一个请求参数
语法：@ApiImplicitParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描
述”,dateType="变量类型”,paramType="请求方式”
· header --> 请求参数的获取：@RequestHeader· query --> 请求参数的获取：@RequestParam· path（用于restful接口）--> 请求参数的获取：
@PathVariable· body（不常用）· form（不常用）
）@ApiImplicitParams： 多个请求参数
@ApiParam：单个参数描述
语法：@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描
述”,dateType="变量类型”,paramType="请求方式”）@ApiResponse：HTTP响应其中1个描述,响应配置
语法：@ApiResponse(code = 400, message = "Invalid user supplied")@ApiResponses：HTTP响应整体描述
语法：@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })@ApiModel：用对象实体来作为入参
@ApiProperty：用对象接实体收参数时，描述对象的一个字段
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息

案例代码

/**** Swagger2配置类* 通过@Configuration注解，让Spring来加载该类配置。* 再通过@EnableSwagger2注解来启用Swagger2。* */
@EnableSwagger2
@Configuration
public class SwaggerConfig {/*** 创建API应用* apiInfo() 增加API相关信息* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，* 本例采用指定扫描的包路径来定义指定要建立API的目录。**/@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.ywq.springbootbysjday1.controller"))//扫描路径.paths(PathSelectors.any())//定义哪些路径的接口需要生成文档.build();}/*** 创建该API的基本信息（这些基本信息会展现在文档页面中）* 访问地址：http://项目实际地址/swagger-ui.html*/private ApiInfo apiInfo() {Contact  contact = new Contact("ywq", "http://www.apesource.com", "wangyanyi_enginner@163.com");return new ApiInfoBuilder().title("疫情防控数据采集发布平台")//文档首页标题.version("1.0")//文档版本.description("新型冠状病毒肺炎 - 疫情防控数据采集发布平台后端接口说明文档")//文档描述信息.contact(contact)//创建者信息.build();}@RestController
@RequestMapping("/user")
@Api(tags = "一个用来测试swagger注解的控制器",value = "/user")
public class UserController {/************************************修饰参数****************************************/@GetMapping(value ="/findByName")@ApiOperation(value = "通过名字查询的方法")public Result findByName(@RequestParam String userName){if(userName.equals("赵老师")){return new Result(true,"查询成功","赵老师");}else{return new Result(false,"查询失败",null);}}
//
//    @GetMapping(value ="/findByNameAndSex")
//    @ApiOperation(value="根据用户名与性别查询")
//    public Result findByNameAndSex(String userName,String sex){
//        if(userName.equals("赵老师")){
//            return new Result(true,"查询成功","赵老师");
//        }else{
//            return new Result(false,"查询失败",null);
//        }
//    }
//
//
//
//    @GetMapping(value ="/findByAge/{age}")
//    @ApiOperation(value="根据用年龄查询", notes="描述的具体信息可以省略")
//    public Result findByAge(@PathVariable("age") Integer userAge){
//        if(userAge > 18){
//            return new Result(true,"查询成功","赵老师");
//        }else{
//            return new Result(false,"查询失败",null);
//        }
//    }
//
//    @PostMapping(value ="/saveAdmin1")
//    @ApiOperation(value="新增管理员信息1", notes="描述的具体信息可以省略")
//    public Result saveAdmin1(Admin admin){
//        if(admin.getAdminId() > 10){
//            return new Result(true,"查询成功","赵老师");
//        }else{
//            return new Result(false,"查询失败",null);
//        }
//    }
//@PostMapping(value ="/saveAdmin2")@ApiOperation(value="新增管理员信息2", notes="描述的具体信息可以省略")public Result saveAdmin2(@RequestBody Admin admin){if(admin.getAdminId() > 10){return new Result(true,"查询成功","赵老师");}else{return new Result(false,"查询失败",null);}}//
//    /************************************返回值****************************************/
//    @DeleteMapping(value ="/deleteById/{id}")
//    @ApiOperation(value="根据用户编号删除信息", notes="")
//    public Admin deleteById(@PathVariable("id") Integer userId){
//        return new  Admin(1,"张三","张三","张三",new Date(System.currentTimeMillis()));
//    }@ApiModel(value = "管理员实体列")
public class Admin {@ApiModelProperty(name = "adminId",value = "管理员编号",example = "001")private int adminId;//管理员编号@ApiModelProperty(name = "adminLoginAccount",value = "管理员登录账号",example = "13991267980")private String adminLoginAccount;//管理员登录账号（手机号码）@ApiModelProperty(name = "adminLoginPassword",value = "登录登录密码",example = "123456")private String adminLoginPassword;//登录登录密码（默认为手机号码后8位）@ApiModelProperty(name = "adminRole",value = "管理员角色",example = "管理员")private String adminRole;//管理员角色（超级管理员或普通管理员）@ApiModelProperty(name = "adminLastLoginTime",value = "最后登录时间")private Date adminLastLoginTime;//最后登录时间（2020年03月14日 15:30:40）
}@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "控制器方法返回值",description = "自定义结果集")
public class Result {@ApiModelProperty(name = "falge",value = "结果集状态",example = "true")private boolean falge;//状态@ApiModelProperty(name = "message",value = "提示信息",example = "查询成功")private String message;//提示信息@ApiModelProperty(name = "data",value = "返回数据")private Object data;//返回数据
}