Swagger注解及SwaggerUI的使用

swagger注解及swaggerUI的使用

一、swagger注解

API详细说明——注释汇总

作用范围	API	使用位置
对象属性	@ApiModelProperty	用在输入参数对象的字段上
协议集描述	@Api	用于controller类上
协议描述	@ApiOperation	用在controller的方法上
Response集	@ApiResponses	用在controller的方法上
Response	@ApiResponse	用在 @ApiResponses里边
非对象参数集	@ApiImplicitParams	用在controller的方法上
非对象参数描述	@ApiImplicitParam	用在@ApiImplicitParams的方法里边
描述返回对象的意义	@ApiModel	用在返回对象类上

6.1. @api

Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源，使用方式：

@Api(value = "/user", description = "Operations about user")

与Controller注解并列使用。 属性配置：

属性名称	备注
value	url的路径值
tags	如果设置这个值，value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏

在SpringMvc中的配置如下：

@Controller
@RequestMapping(value = "/api/user", produces = {APPLICATION_JSON_VALUE, APPLICATION_XML_VALUE})
@Api(value = "用户管理")
public class UserController {}

6.2. @ApiOperation

ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义,使用方式：

@ApiOperation(value = "Find purchase order by ID", notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions", response = Order, tags = {"用户管理"})

与Controller中的方法并列使用。
属性配置：

属性名称	备注
value	url的路径值
tags	如果设置这个值，value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏
response	返回的对象
responseContainer	这些对象是有效的 "List", "Set" or "Map".，其他无效
httpMethod	"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
code	http的状态码 默认 200
extensions	扩展属性

在SpringMvc中的配置如下：

@RequestMapping(value = "/query/{userId}", method = GET)
@ApiOperation(value = "查询用户", notes = "通过用户id查询用户", response = Response.class, tags = { "用户管理" })
public Response<User> getUserById(@PathVariable("userId") String userId) throws NotFoundException {
    User user = userService.getUserById(userId);
    return Response.ok(user);
}

6.3. @ApiParam

ApiParam请求属性，使用方式：

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)

与Controller中的方法并列使用。

属性配置：

属性名称	备注
name	属性名称
value	属性值
defaultValue	默认属性值
allowableValues	可以不配置
required	是否属性必填
access	不过多描述
allowMultiple	默认为false
hidden	隐藏该属性
example	举例子

在SpringMvc中的配置如下：

public Response<User> getUserById(@ApiParam(value = "用户id", allowableValues = "range[1,5]", required = true) @PathVariable("userId") String userId)

通常是将swagger相关的注解用在Controller类中，如果Controller类实现了接口，也可以将swagger注解用在Controller的接口上，如下所示。

6.4.@ApiModel和@ApiModelProperty

@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）

@ApiModelProperty：描述一个model的属性。

二、swaggerUI的使用

SpringBoot与Swagger2整合：

第一步：新建springboot项目，在pom.xml文件中引入依赖：

<!-- swagger2 -->
<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>

上面两个依赖的作用:

springfox-swagger2依然是依赖OSA规范文档，也就是一个描述API的json文件，而这个组件的功能就是帮助我们自动生成这个json文件， 
springfox-swagger-ui就是将这个json文件解析出来，用一种更友好的方式呈现出来。

第二步：创建api或controller，提供后端接口方法：

package abc.baidu.google.map.controller;

import abc.baidu.google.map.model.TbsAreaSum;
import abc.baidu.google.map.service.TbsAreaSumService;
import abc.baidu.google.map.utils.RespResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.util.List;

@Api(tags = "经纬度数据管理")
@RestController
@RequestMapping(value = "/ips/map")
public class TbsAreaSumController {

    @Autowired
    private TbsAreaSumService tbsAreaSumService;

    @ApiOperation(value = "查询全部地图数据",notes = "查询全部地图数据",response = RespResult.class,tags = {"经纬度数据管理"})
    @GetMapping
    @ResponseBody
    RespResult<List<TbsAreaSum>> findAll(){
        return RespResult.ok(tbsAreaSumService.findAll());
    }

    @ApiOperation(value = "批量修改经纬度",notes = "批量修改经纬度",response = RespResult.class,tags = {"经纬度数据管理"})
    @PutMapping
    @ResponseBody
    RespResult<List<TbsAreaSum>> updateBatchLonLat(){
        List<TbsAreaSum> sumList = tbsAreaSumService.findAll();
        tbsAreaSumService.updateBatchLonLat(sumList);
        return RespResult.ok(sumList);
    }

}

第三步：配置Swagger2

现在Swagger2还不能生成API文档，因为还没有对它进行配置。需要创建一个配置类，进行如下配置：

package abc.baidu.google.map.utils;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //下面使用的basePackage方法中扫描的是controller类所在的包路径
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().
                apis(RequestHandlerSelectors.basePackage("abc.baidu.google.map")).paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("经纬度转换服务").description("经纬度转换服务API文档").license("ABC 1.0").licenseUrl("").termsOfServiceUrl("").version("1.0.0").build();
    }

}

springfox为我们提供了一个Docket（摘要）类，我们需要把它做成一个Bean注入到spring中， 显然，我们需要一个配置文件，并通过一种方式（显然它会是一个注解）告诉程序，这是一个Swagger配置文件。

springfox允许我们将信息组合成一个ApiInfo的类，作为构造参数传给Docket（当然也可以不构造这个类，而直接使用null，但是你的这个API就太low了）。

经过以上三步，springboot与swaggerUI已经整合完毕，现在启动项目，在浏览器中访问项目的swagger-ui页面。

可能遇到的问题：

1、springboot2.6以上版本与swagger2的冲突：

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException.

原因是在springboot2.6.0中将SpringMVC 默认路径匹配策略从AntPathMatcher 更改为PathPatternParser，导致出错。

解决方法：在配置文件application.yml中加上如下配置即可。

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

2、在浏览器上访问swagger-ui页面弹出如下提示：

这是因为项目启动时扫描不到swagger配置类。这次由于将swagger配置类放在code-generate-common模块中，而启动类在code-generate-biz模块中，启动类默认扫描启动类所在包及其子包下的所有带有spring注解的类，所以扫描不到其他项目中的类，除非其他项目的包名与启动类的包名相同。

解决方法：方法1、将swagger配置类放置到启动类所在的模块中。

方法2、在启动类上加上@ComponentScan注解，扫描多个模块包名的共同前缀。如果多个模块的包名没有相同的前缀，则@ComponentScan注解中需要写上启动类所在模块的包名和swagger配置类所在模块的包名。