1、前言
①在前后端分离开发中，一般需要构建一份API文档来描述所有接口信息，文档工作量巨大，需要包含接口地址、请求参数以及返回值等，且维护不方便，一旦接口发生变化就需要修改文档。
②Swagger的出现可以帮助开发人员快速设计、构建、记录、使用RESTFul API/Web服务。它将代码和文档融为一体，完美解决上述问题，将开发人员的精力集中到业务中，而不是繁琐的文档。
③网上很多Swagger教程均基于Swagger2，现均已过时，而本文将带来全新Swagger3.0教程，以最简单的方式实现Swagger3(OAS3)快速配置上手，实现API接口文档自动化。
2、开发工具及版本
JAVA11或者JAVA13
Spring-boot 2.5+
3、Swagger3.0与Swagger2的主要差异：
①Swagger3通过@EnableOpenApi注解开启应用，而Swagger2通过@EnableSwagger2注解开启应用。
②依赖有所不同，见下文。
③访问网址不同，Swagger3是http://localhost:8080/swagger-ui/index.html，Swagger2是http://localhost:8080/swagger-ui.html，这个要特别注意。
4、项目整合使用Swagger3.0配置完整过程
1、创建Spring-boot Web项目，添加Swagger3.0相关依赖，代码如下：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>原Swagger2需要引入下面两个依赖，这里我们了解即可。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>2、接下来创建Swagger3.0配置类Swagger3Config，项目结构树和代码如下：
这里我们特别注意：
①apis(RequestHandlerSelectors.basePackage("com.example.demohelloworld.swagger3.controller"))，表明扫描该包下面所有的Controller接口类。
②apis(RequestHandlerSelectors.any())表明扫描所有满足条件的Controller接口类。
③paths(Predicate.not(PathSelectors.regex("/error.*")))表明排除某个路径，在RESTFul接口中有时候需要排除"/error.*"等接口，只需要加入上述代码即可，regex()表明符合正则的路径。
④还有一个地方很容易被忽略，Swagger3的访问网址swagger-ui/index.html是放在META-INF/resources下面，所以我们需要加入资源映射，确保能够访问。映射的地址是/META-INF/resources/webjars/springfox-swagger-ui/。
package com.example.demohelloworld.swagger3.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.function.Predicate;
@Configuration
//@EnableOpenApi开启SWAGGER3.0
@EnableOpenApi
public class Swagger3Config implements WebMvcConfigurer {
@Bean
//同Swagger2相似,主要是配置一个Docket
Docket docket(){
//DocumentationType.OAS_30,原Swagger2选择DocumentationType.SWAGGER_2
return new Docket(DocumentationType.OAS_30)
.select()
//通过apis方法配置要扫描的controller的位置
.apis(RequestHandlerSelectors.basePackage("com.example.demohelloworld.swagger3.controller"))
//通过paths方法配置路径
.paths(PathSelectors.any())
//设置需要排除的路径(如果需要)
.paths(Predicate.not(PathSelectors.regex("/error.*")))
.build().apiInfo(new ApiInfoBuilder()
//设置文档标题
.description("Swagger3测试API接口文档")
//设置联系人信息
.contact(new Contact("API作者","https://www.csdn.net","lulc@163.com"))
//设置版本号
.version("1.1")
//设置文档抬头
.title("API测试文档")
//设置授权
.license("License By lulu")
//设置授权访问网址
.licenseUrl("https://swagger.io")
.build());
}
@Override
//swagger-ui/index.html在META-INF/resources下面,添加资源映射确保URL能够访问
public void addResourceHandlers(ResourceHandlerRegistry registry){
registry.addResourceHandler("/swagger-ui/**").addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/")
.resourceChain(false);
}
}
3、Swagger3Config配置完成后，我们创建一个测试接口ApiController就可以开始测试了。
首先我们了解Swagger3一些常用注解的含义：
@Api：用在类上，用来描述整个Controller接口信息。
@ApiOperation：用在方法上，用来描述方法的基本信息，value是对方法作用的简短描述，notes则是该方法的详细描述。
@ApiImplicitParam：用在方法上，用来描述方法的参数，paramType是指方法参数类型，可选值有path(参数获取方式@PathVariable)、query(参数获取方式@RequestParam)、header(参数获取方式@RequestHeader)、body(参数获取方式@RequestBody)以及form，name表示参数名字，和参数名字对应，value则是参数描述信息。required表示该字段是否必填，defaultValue表示该字段的默认值，注意，这里的required和defaultValue不具备真正的约束性仅为文档显示，真正的还需要在@RequestParam中设置。
@ApiImplicitParams：如果是多参数，可将多个参数放在@ApiImplicitParams中，格式为@ApiImplicitParams({@ApiImplicitParam(paramType="query",name="username"),@ApiImplicitParam(paramType="path",name="userid")})。
@ApiResponse：对响应结果的描述，code表示响应码，@message表示描述信息，如果有多个@ApiResponse，可以放在一个@ApiResponses中。
@ApiResponses：格式为@ApiResponses({@ApiResponse(code = 200,message = "删除成功！"),@ApiResponse(code = 500,message = "删除失败！")})。
@ApiModel：一般用于响应类上，表示一个返回响应数据的信息(如updateUse方法，请求参数无法使用@ApiImplicitParam注解进行描述的时候)。
@ApiModelProperty：用在属性上，描述响应类的属性。
@ApiIgnore：表述不对某个接口生成文档，即忽略这个接口。
接下来我们在Controller层创建测试接口ApiController，将以上注解写入相应的位置。在RESTFul API接口中，书写注解的位置可以是@Repository，也可以是@Service。
Controller调用Service，Service调用Dao(Repository)，是常见的MVC三层模型。而Swagger灵活的地方就是可以在这三层中需要的位置任意书写。
package com.example.demohelloworld.swagger3.controller;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
@RestController
//@Api：用在类上，用来描述整个Controller接口信息。
@Api(tags = "用户数据接口")
public class ApiController {
//@ApiOperation：用在方法上，用来描述方法的基本信息
@ApiOperation(value = "查询用户" ,notes = "根据ID查询用户")
//@ApiImplicitParam：用在方法上，用来描述方法的参数
@ApiImplicitParam(paramType = "path",name = "id",value = "用户id",required = true,dataType = "String",dataTypeClass = String.class)
@GetMapping("/user/{id}")
public String getUserByID(@PathVariable Integer id){
return "userid:"+ id;
}
//@ApiResponse：对响应结果的描述
@ApiResponses({@ApiResponse(code = 200,message = "删除成功！"),@ApiResponse(code = 500,message = "删除失败！")})
@ApiOperation(value = "删除用户", notes = "删除用户BYid")
@DeleteMapping("/user/{id}")
public String deleteUserById(@PathVariable Integer id){
return "删除用户："+id;
}
@ApiOperation(value = "添加用户",notes = "添加一个用户，传入用户名和地址")
//@ApiImplicitParams：如果是多参数，可将多个参数@ApiImplicitParam放在@ApiImplicitParams中
@ApiImplicitParams({@ApiImplicitParam(paramType = "query",name = "username",value = "传入用户名",required = true,defaultValue = "lulu",dataType = "String",dataTypeClass = String.class),
@ApiImplicitParam(paramType = "query",name = "address",value = "传入地址",required = true,defaultValue = "深圳",dataType = "String",dataTypeClass = String.class)})
@PostMapping("/user")
public String addUser(@RequestParam String username,@RequestParam String address){
return "添加用户："+username+" 地址："+address;
}
@ApiOperation(value = "修改用户",notes = "修改用户，传入用户信息")
@PutMapping("/user")
public String updateUser(@RequestBody Users user){
return "修改用户"+user.getUsername()+user.getAddress();
}
//@ApiIgnore：表述不对某个接口生成文档
@GetMapping("/ignore")
@ApiIgnore
public void ignore(){
}
//@ApiModel：一般用于响应类上，表示一个返回响应数据的信息
@ApiModel(value = "用户实体类",description = "用户信息描述")
public static class Users{
//@ApiModelProperty：用在属性上，描述响应类的属性
@ApiModelProperty(value = "用户名")
private String username;
@ApiModelProperty(value = "用户地址")
private String address;
public String getUsername() {
return username;
}
public String getAddress() {
return address;
}
public void setUsername(String username) {
this.username = username;
}
public void setAddress(String address) {
this.address = address;
}
}
}
4、启动项目，输入http://localhost:8080/swagger-ui/index.html开始测试，效果图如下
接下来就可以在Swagger中开启各项API接口测试了，调试也就变得非常简单。(可以暂时告别Postman等第三方接口测试工具了)
5、补充一点，如果系统设置的有拦截，还需要排除一下Swagger3.0的相关资源，我们排除以下四种资源即可。
.excludePathPatterns("/swagger**/**") .excludePathPatterns("/webjars/**") .excludePathPatterns("/v3/**") .excludePathPatterns("/doc.html");
5、总结
全新Swagger3.0的易用性还是非常不错的，依赖相比2.0减少一个，配置更加简单，新版的页面风格更加现代化，有耳目一新的感觉。
后续我还将更新如何利用Spring Jpa/Mysql/Swagger3快速搭建一个生产级RESTFul API接口，欢迎关注、留言、转发。