使用Swagger2构建RESTful API

吐槽了一阵公司提供的记录接口文档工具后，抽个空档时间搭了个RESTful风格的API文档Demo，感觉还不错，在这里记录一下，技术栈使用Spring Boot+Swagger2。

Swagger可以很轻松的整合到Spring Boot中，在代码里根据swagger语法打些标签，生成可预览的Api文档，减少了很多时间写API接口文档上，让维护文档和修改代码整合一体了，并且可以与Spring MVC程序配合组织出强大RESTful API文档，也能提供了强大的页面测试功能来调试测试每个接口。

![](./使用Swagger2构建RESTful API.jpg)

下面分步骤走一遍，简单记录一下。

创建Spring Boot项目，添加Swagger2依赖

在IDEA中创建Spring Boot项目，记得依赖勾选web，项目是由maven管理，在pom.xml文件中添加依赖：springfox-swagger2和spring-swagger-ui，版本这里选择的2.5.0。

1
2
3
4
5
6
7
8
9
10
11
12
 <!-- springfox swagger -->
<dependency>
	<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
		<version>2.5.0</version>
</dependency>
<!-- swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.5.0</version>
</dependency>

创建Swagger2配置类

在Application.java同级创建Swagger2的配置类Swagger2Config。

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
/**
 * 通过`@Configuration`注解，让Spring来加载该类配置
 * 通过`@EnableSwagger2`注解来启用Swagger
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    /**
     * createRestApi函数创建Docket的Bean
     * @return
     */
    @Bean("welcome")
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 指定模块区分
                .groupName("欢迎模块")
                // select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger-ui来展现
                .select()
                // 采用指定扫描的包路径来定义，Swagger2会扫描该包下所有Controller定义的API，并产生文档内容
                // 除了被@ApiIgnore指定的请求外
                .apis(RequestHandlerSelectors.basePackage("com.space.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * apiInfo创建该Api的基本信息（这些基本信息会展现在文档页面中）
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("这是一个Demo项目")
                .termsOfServiceUrl("http://localhost:9999/swagger-ui.html")
                .contact(new Contact("pross","https://pross.space",""))
                .version("1.0")
                .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
@RestController
@RequestMapping(value = "/welcome")
public class HelloController {

    // 通过@ApiOperation注解来给API增加说明
    @ApiOperation(value = "第一个接口",notes = "欢迎语")
    // 通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。
    @ApiImplicitParam(name = "name",value = "姓名",required = true,dataType = "String", paramType = "query")
    @RequestMapping(value = "/hello",method = RequestMethod.GET)
    public String hello(@RequestParam(name="name",defaultValue = "pross") String name){
        return "hello "+name;
    }

    // 通过@ApiOperation注解来给API增加说明
    @ApiOperation(value = "第二个接口",notes = "欢迎语2")
    // 通过@ApiImplicitParams注解来给参数增加说明
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name1",value = "姓名1",required = true,dataType = "String",paramType = "query"),
            @ApiImplicitParam(name = "name2",value = "姓名2",required = true,dataType = "String",paramType = "query")
    })
    @RequestMapping(value = "/hello2",method = RequestMethod.POST)
    public String hello2(@RequestParam(name="name1",defaultValue = "pross1") String name1,
                         @RequestParam(name="name2",defaultValue = "pross2") String name2){
        return "hello "+name1+" and "+name2;
    }
}

这里踩了一个坑，关于paramType参数的设置，这个属性是指定参数放的位置的。接口使用@RequestParam获取参数的话需要指定paramType = "query"。接口使用@PathVariable获取，需指定paramType=path。如果POST请求，则包装的实体类需要@ApiModel注解，字段需要@ApiModelProperty注解。

完成上述步骤上，启动Spring Boot程序，访问http://localhost:8080/swagger-ui.html（自动替换端口），就能看到文章开头展示的RESTful API的页面。我们可以再点开具体的API请求，看到我们定义的各种API信息。

API文档访问与调试

Swagger除了查看接口功能外，还提供了调试测试功能，我们可以在上图定义的白色空白出填写传入的name值即可，点击下方Try it out！按钮，即可完成了一次请求调用！

完。