在前后端分离的开发中，后端需要给前端提供API接口文档，这是非常重要的一步。但是，接口文档的编写以及更新也是在开发过程中需要耗费很多的时间，特别是一些参数的内容，容易因为错误的编写而导致前端人员使用不了接口。Swagger便是为了解决这个问题而生的，在开发的过程中，根据后端开发人员配置的参数，自动生成API文档，本篇文章就是关于在Springboot项目中使用这个插件的基础功能介绍。
一、Swagger相关注解
| 注解 | 介绍 |
|---|---|
| @Api | @Api 用在类上，说明该类的作用。可以标记一个 Controller 类作为 Swagger 文档资源 |
| @ApiParam | 用于 Controller 中方法的参数说明 |
| @@ApiOperation | 用在 Controller 里的方法上，说明方法的作用，每一个接口的定义 |
| @ApiImplicitParam 和@ApiImplicitParams | 用于方法上，为单独的请求参数进行说明 |
| @ApiModel | 用于字段，表示对 model 属性的说明 |
| @ApiModelProperty | 表示对类进行说明，用于实体类中的参数接收说明 |
| @ApiResponse 和@ApiResponses | @ApiResponse 用于方法上，说明接口响应的一些信息；@ApiResponses 组装了多个 @ApiResponse |
这里主要做一个简单的介绍，具体的看下面在springboot项目具体的使用。
二、在springboot项目中的实际应用
（一）引依赖
<!--Swagger依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--Swagger UI依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
这里引入的两个依赖，第一个引入的是swagger的依赖，引入这个依赖后，可以查看到返回的json文档，非常繁琐复杂，可读性极差，这时候就需要一个展示UI，引入后者就是是一个swagger展示UI的依赖。
（二）配置swagger
@Configuration
@EnableSwagger2
@ComponentScan(basePackages = {
"com.example.api.controller" })
public class SwaggerConfig {
@Bean
public Docket buildDocket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInf())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.api.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo buildApiInf(){
return new ApiInfoBuilder()
//页面标题
.title("秒杀商城API文档")
//描述
.description("简单优雅的restful风格")
//创建人信息
.contact(new Contact("Curry-Kun","127.0.0.1:8080/","[email protected]"))
.termsOfServiceUrl("")
//版本号
.version("1.0")
.build();
}
}
（三）配置接口类和实体类
1.controller层
@RestController
@RequestMapping("/miaosha")
@Api(tags = "秒杀功能模块API")
public class MiaoshaAPIController {
@Autowired
ProductService productService;
@ApiImplicitParams({
@ApiImplicitParam(name = "pageNo",value = "页码数",required = true,dataType = "int",paramType = "query"),
@ApiImplicitParam(name = "pageSize",value = "展示条数",required = true,dataType = "int",paramType = "query")
})
/**
* 商品列表页api
* @request
* pageNo
* pageSize
* @response
* success
* fail
*
* */
@ApiOperation(value = "查询系统秒杀商品列表",notes = "采取分页的形式展示，需要pageNo页码数和pageSize每页展示条数")
@PostMapping(value = "product_list_api")
public ResponseResult product_list_api(@RequestParam(value = "pageNo",defaultValue = "1")int pageNo,
@RequestParam(value = "pageSize",defaultValue = "6")int pageSize,
User user){
if(user == null){
return ResponseResult.error(ResponseCode.NO_LOGIN);
}
PageInfo<ProductVo> page = productService.listProcuctVo(pageNo,pageSize);
return ResponseResult.success(page);
}
这里涉及到@Api、@ApiImplicitParams、 @ApiImplicitParam、 @ApiOperation这几个注解的使用，从上面代码中可以更加具体的看出他们各自的作用。
以为返回的结果都是封装在ResponseResult中，所以对它也需要进行注释
@Data
@ApiModel
public class ResponseResult<T> {
@ApiModelProperty(value = "返回状态码")
private int code;
@ApiModelProperty(value = "返回信息")
private String msg;
@ApiModelProperty(value = "返回数据")
private T data;
/**
* 不同的data数据类型对应不同的ResponseResult的类型
* */
/**
*return code message data 方法构造器
* */
public ResponseResult(ResponseCode rc,T data) {
this.data = data;
this.msg = rc.msg;
this.code = rc.id;
}
/**
* return code message
* */
public ResponseResult(ResponseCode rc) {
this.msg = rc.msg;
this.code = rc.id;
}
/**
* success
* */
public static <T> ResponseResult<T> success(T data){
return new ResponseResult<T>(ResponseCode.SERVER_SUCCESS,data);
}
/**
* error
* */
public static <T> ResponseResult<T> error(ResponseCode rc){
return new ResponseResult<T>(rc);
}
}
这里涉及@ApiModel、@ApiModelProperty注解的使用。
启动项目，访问http://{ip}:{端口}/swagger-ui.html#/
（四）优化UI
上面这个UI在使用中还是不是很方便，还可以做一个更加人性化的页面，使用swagger-bootstrap-ui
1.引入依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.6</version>
</dependency>
这时候就需要访问http://{ip}:{端口}/doc.html
同时支持在线调试，只要你编写的注解足够详细，小白也能看得懂。
三、找不到生成的API文档页面怎么办？
1.出现页面无法访问错误:No mapping for GET /swagger-ui.html
这种情况的出现是系统将请求的swagger-ui.html当成了参数进行传递，这样肯定会出错。这个时候就需要修改WebMvcConfigurer，拦截swagger-ui.html，并配置文件位置。
@Configuration
public class WebConfig implements WebMvcConfigurer{
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("doc.html")//swagger-ui.html
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
2.访问之后出现空白页
出现这种情况，一定要确认swagger使用的UI依赖是否引入正常，很可能是依赖没有引进去，造成找不到swagger-ui.html文件，去dom.xml中追踪一下或者在查看系统依赖，如果确认没有需要的UI依赖，可以将依赖降级使用。