Spring Boot 整合——swagger2使用_allowablevalues

引入swagger配置

如今的开发，前后端分离越来越普遍。日常我们工作的时候前后端配合的时候，后端通常需要提供一份方便前端使用的API文档。而一篇文档的准确、可理解性的好坏是保证合作能否稳步进行的关键。而Swagger就是一种可以根据我们在代码中的注释来自动生成在线API文档的工具。有了Swagger不仅节省了大量编写API文档的时间，而且提供了调试的渠道。

依赖引入

使用swagger我们需要引入一个swagger核心组件以及与其配套的一个UI组件

<!-- Swagger -->
<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>
1
2
3
4
5
6
7
8
9
10
11

代码配置

代码层面上我们需要配置一个swagger启动的Docket环境。以及swagger的文档信息。

@Configuration
public class SwaggerConfig {

    /**
     * 创建swagger运行的docket环境
     * @return
     */
    @Bean
    public Docket createRestApi() {
        // 使用Docket启动，
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 扫描基础包
                .apis(RequestHandlerSelectors.basePackage("dai.samples.swagger"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建swagger的api信息
     * @return
     */
    private ApiInfo apiInfo() {
        // 配置名称地址和email
        Contact contact = new Contact("大·风","https://blog.csdn.net/qq330983778","email");
        return new ApiInfoBuilder()
                // 标题
                .title("Spring Boot 整合Swagger")
                // 描述
                .description("这个一个demo项目")
                .termsOfServiceUrl("https://blog.csdn.net/qq330983778")
                .version("1.0")
                .contact(contact)
                .build();
    }
    
    
}


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

然后我们在启动类上添加@EnableSwagger2注解

@EnableSwagger2
@SpringBootApplication
public class SwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }
}

1
2
3
4
5
6
7
8
9

请求地址

此时我们请求：http://localhost:8000/swagger-ui.html。会进入swagger页面

因为此时我们只设置了一个简单的controller所以只会显示一个接口默认的文档格式

@Api
@RestController
@RequestMapping("BaseSwagger")
public class BaseSwaggerController {

    /**
     * 一个基础的测试
     * @param request
     * @return
     */
    @ApiOperation(value="测试基础对象")
    @RequestMapping(value = "base",method = RequestMethod.POST)
    public String base(ServletRequest request) {
        String contentType = request.getContentType();
        return "contentType：" + contentType;
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

swagger使用场景

上面是一个非常基础，根据默认逻辑生成的文档格式。下面我们介绍下我们想实现更多自己的业务逻辑时候的参数设置

controller上的注解

假如我们想给Controller添加更多的信息的时候可以设置这些内容

@Api(value = "控制器类型",
        tags = "测试控制器类型注解内容")
@RestController
@RequestMapping("class")
public class TestClassAnnotationsController {

    /**
     * 一个基础的测试
     * @param request
     * @return
     */
    @ApiOperation(value="测试基础对象", notes="测试基础对象备注",httpMethod = "POST")
    @RequestMapping(value = "base",method = RequestMethod.POST)
    public String base(ServletRequest request) {
        String contentType = request.getContentType();
        return "contentType：" + contentType;
    }

}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

此时API文档上不再像上面例子一样显示类名称的样式，而是会显示tags中的内容。

请求参数添加注解

当然除了增加堆controller的描述，我们可以增加对具体请求的信息描述

基础类型

假如我们传入的参数是分开的数据而非一个对象的时候，我们可以这样补充其信息

 /**
     * 测试请求参数添加描述
     * @param name
     * @param age
     * @return
     */
    @ApiOperation(value="参数请求(请求描述)", 
            notes="请求的注释(注释)",
            httpMethod = "POST",
            response = String.class
            )
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name",value = "name的描述",defaultValue = "默认值",
                    dataTypeClass = String.class,paramType = "query",
                    example = "参数实例值"),
            @ApiImplicitParam(name = "age",value = "age的描述",allowableValues = "1,2,3",
                    dataTypeClass = Integer.class,paramType = "query")
    })
    @RequestMapping(value = "base",method = RequestMethod.POST)
    public String testBaseParams(String name,Integer age) {
        log.info("传入参数:name:{},age:{}",name,age);
        return "传入参数:name:"+name+",age:"+age;
    }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

我们在上面添加了这些内容，
在方法上，首先我们提供了接口的作用value，而notes作为详细描述，然后我们声明了请求方法类别。
在参数上我们生命了参数的描述，设置了默认值，参数的类型，以及参数传递类别。同时声明了默认值

可以看到针对这个方法每个参数作用到文档中的样子。

而我们点击Try it out的时候默认值和选项也会发挥作用。

对象类型

当我们请求是一个对象的时候

不对模型设置文档注解

此时我们请求一个没有添加文档注解的对象。

    /**
     * 测试对入参对象不添加注解
     * @param user
     * @return
     */
    @ApiOperation(value="参数为对象请求,此时不对参数加额外注释(请求描述)",
            notes="参数为对象请求的注释(注释)",
            httpMethod = "POST")
    @RequestMapping(value = "bean",method = RequestMethod.POST)
    public String testBeanParams(User user) {
        log.info("传入参数:",JSON.toJSONString(user));
        return "传入参数:"+JSON.toJSONString(user); 
    }
1
2
3
4
5
6
7
8
9
10
11
12
13

这个时候swagger可以将对象参数进行解析，但是因为没有添加注解，所以显示的知识属性名称。

对模型设置文档注解

@Data
@ApiModel(value = "子类的请求对象",
        description = "请求对象描述",
        parent = QueryBaseRequest.class)
public class QueryUserRequest extends QueryBaseRequest {
    
    @ApiModelProperty(name = "name",
            value = "name值",
            dataType = "String",
            example = "默认显示的值",
            allowEmptyValue = true)
    private String name;

    @ApiModelProperty(name = "param1",
            value = "这个参数会被隐藏",
            dataType = "String",
            required = true,
            hidden = true)
    private String param1;


    @ApiModelProperty(name = "param2",
            value = "参数2，这个参数必填",
            dataType = "String",
            required = true,
            allowableValues = "值1,值2,值3")
    private String param2;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

此时对参数的对象设置文档注解，再去查看API文档页面

此时就可以显示文档中设置的内容了。

请求返回内容的注解

swagger除了支持对请求controller和请求方法，以及入参进行注解，还支持对返回内容提供注解。

配置返回对象

通常我们不仅要向他人提供传递参数的文档还需要提供返回内容，正确以及错误结果的内容，这个时候可以使用ApiResponses注解

• 正常内容的注解

@Data
@ApiModel(value = "用户的包装类",description = "用户的包装类描述")
public class UserWrapper {

    @ApiModelProperty(name = "id",
            value = "id的值",
            dataType = "java.lang.Long")
    private Long id;

    @ApiModelProperty(name = "name",
            value = "name值",
            dataType = "String")
    private String name;
    @ApiModelProperty(name = "age",
            value = "age值",
            dataType = "java.lang.Integer")
    private Integer age;
    @ApiModelProperty(name = "money",
            value = "money值",
            dataType = "java.lang.Double")
    private Double money;

    public UserWrapper(User user) {
        this.id = user.getId();
        this.name = user.getName();
        this.age = user.getAge();
        this.money = user.getMoney();
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

-错误内容的注解

@Data
@ApiModel(value = "错误的返回值",description = "错误的返回值")
public class ErrorRest {
    /**
     * 返回code
     */
    @ApiModelProperty(name = "code",
            value = "错误的code",
            dataType = "java.lang.Integer",
            example = "500")
    private Integer code;

    /**
     * 返回错误信息
     */
    @ApiModelProperty(name = "name",
            value = "错误信息",
            dataType = "String",
            example = "错误数据")
    private String message;

    /**
     * 返回错误的结果集
     */
    @ApiModelProperty(name = "data",
            value = "错误数据",
            dataType = "Object",
            example = "{}")
    private String data;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

请求内容

    @ApiOperation(value="对象请求返回对象(请求描述)",
            notes="对象请求返回对象的注释(注释)",
            httpMethod = "POST",
            responseHeaders = {
                    @ResponseHeader(name="dai",description = "头信息的补充")
            },
            code = 201)
    @ApiResponses({
            @ApiResponse(code = 200,message = "成功",response = UserWrapper.class),
            @ApiResponse(code = 500,message = "服务器错误",response = ErrorRest.class)
    })
    @RequestMapping(value = "beanToBean",method = RequestMethod.POST)
    public UserWrapper testBeanParamsReturnBean(User user) {
        log.info("传入参数:",JSON.toJSONString(user));
        return new UserWrapper(user);
    }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

此时查看API文档，我们将展示内容切换至Model就可以看到配置的内容了。

其他配置

Path类型的参数

    @ApiOperation(value="GET请求注释(请求描述)",
            notes="GET请求注释(注释)",
            httpMethod = "GET")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "id的描述",
                    defaultValue = "2333",
                    dataTypeClass = Integer.class,paramType = "path",
                    example = "2333")
    })
    @RequestMapping(value = "{id}",method = RequestMethod.GET)
    public String testPath(@PathVariable("id") Integer id) {
        log.info("传入参数:",JSON.toJSONString(id));
        return "传入参数:" + id;
    }
1
2
3
4
5
6
7
8
9
10
11
12
13
14

参数的效果

隐藏某些接口

1、可以配置参数idden = true来隐藏这个接口

@Api(value = "控制器隐藏",
        tags = "控制器隐藏(此注解将被隐藏)",
        hidden = true)
@RestController
@RequestMapping("classHidden")
public class TestClassAnnotationsHiddenController {
    
}
1
2
3
4
5
6
7
8

2、 或者使用@ApiIgnore来忽略接口生成

@ApiIgnore(value = "注解标注忽略")
@Api("User相关请求控制器")
@RestController
@RequestMapping("user")
1
2
3
4

模型的文档

在文档下部的Models中可以看到接口返回对象中的数据模型。

页面的替换

对于很多人来说，原生的页面并不是那么习惯。所以现在有很多可以替换swagger默认界面的方法。这一块因为之前并没有准备这块代码，也没有测试网上的那些方法。所以这里就先不说了，有兴趣的可以多搜一搜，有非常多的结果的。

---

本篇文章涉及的源码下载地址：https://gitee.com/daifyutils/springboot-samples

附录：swagger常用注解

基于对象的注解

基于控制器注解配置

基于请求注解配置