Spring Boot 集成 Swagger 构建接口文档

在应用开发过程当中常常须要对其余应用或者客户端提供 RESTful API 接口，尤为是在版本快速迭代的开发过程当中，修改接口的同时还须要同步修改对应的接口文档，这使咱们老是作着重复的工做，而且若是忘记修改接口文档，就可能形成没必要要的麻烦。

为了解决这些问题，Swagger 就孕育而生了，那让咱们先简单了解下。

Swagger 简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

整体目标是使客户端和文件系统做为服务器，以一样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码中，容许 API 始终保持同步。

下面咱们在 Spring Boot 中集成 Swagger 来构建强大的接口文档。

Spring Boot 集成 Swagger

Spring Boot 集成 Swagger 主要分为如下三步：

1. 加入 Swagger 依赖
2. 加入 Swagger 文档配置
3. 使用 Swagger 注解编写 API 文档

加入依赖

首先建立一个项目，在项目中加入 Swagger 依赖，项目依赖以下所示：

<dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <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>

加入配置

接下来在 config 包下建立一个 Swagger 配置类 Swagger2Configuration，在配置类上加入注解 @EnableSwagger2，代表开启 Swagger，注入一个 Docket 类来配置一些 API 相关信息，apiInfo() 方法内定义了几个文档信息，代码以下：

@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // swagger 文档扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.wupx.interfacedoc.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试接口列表")
                .description("Swagger2 接口文档")
                .version("v1.0.0")
                .contact(new Contact("wupx", "https://www.tianheyu.top", "wupx@qq.com"))
                .license("Apache License, Version 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .build();
    }
}

列举其中几个文档信息说明下：

• title：接口文档的标题
• description：接口文档的详细描述
• termsOfServiceUrl：通常用于存放公司的地址
• version：API 文档的版本号
• contact：维护人、维护人 URL 以及 email
• license：许可证
• licenseUrl：许可证 URL

编写 API 文档

在 domain 包下建立一个 User 实体类，使用 @ApiModel 注解代表这是一个 Swagger 返回的实体，@ApiModelProperty 注解代表几个实体的属性，代码以下（其中 getter/setter 省略不显示）：

@ApiModel(value = "用户", description = "用户实体类")
public class User {

    @ApiModelProperty(value = "用户 id", hidden = true)
    private Long id;

    @ApiModelProperty(value = "用户姓名")
    private String name;

    @ApiModelProperty(value = "用户年龄")
    private String age;

    // getter/setter
}

最后，在 controller 包下建立一个 UserController 类，提供用户 API 接口（未使用数据库），代码以下：

@RestController
@RequestMapping("/users")
@Api(tags = "用户管理接口")
public class UserController {

    Map<Long, User> users = Collections.synchronizedMap(new HashMap<>());

    @GetMapping("/")
    @ApiOperation(value = "获取用户列表", notes = "获取用户列表")
    public List<User> getUserList() {
        return new ArrayList<>(users.values());
    }

    @PostMapping("/")
    @ApiOperation(value = "建立用户")
    public String addUser(@RequestBody User user) {
        users.put(user.getId(), user);
        return "success";
    }

    @GetMapping("/{id}")
    @ApiOperation(value = "获取指定 id 的用户")
    @ApiImplicitParam(name = "id", value = "用户 id", paramType = "query", dataTypeClass = Long.class, defaultValue = "999", required = true)
    public User getUserById(@PathVariable Long id) {
        return users.get(id);
    }

    @PutMapping("/{id}")
    @ApiOperation(value = "根据 id 更新用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户 id", defaultValue = "1"),
            @ApiImplicitParam(name = "name", value = "用户姓名", defaultValue = "wupx"),
            @ApiImplicitParam(name = "age", value = "用户年龄", defaultValue = "18")
    })
    public User updateUserById(@PathVariable Long id, @RequestParam String name, @RequestParam Integer age) {
        User user = users.get(id);
        user.setName(name);
        user.setAge(age);
        return user;
    }

    @DeleteMapping("/{id}")
    @ApiOperation(value = "删除用户", notes = "根据 id 删除用户")
    @ApiImplicitParam(name = "id", value = "用户 id", dataTypeClass = Long.class, required = true)
    public String deleteUserById(@PathVariable Long id) {
        users.remove(id);
        return "success";
    }
}

启动项目，访问 http://localhost:8080/swagger-ui.html，能够看到咱们定义的文档已经在 Swagger 页面上显示了，以下图所示：

到此为止，咱们就完成了 Spring Boot 与 Swagger 的集成。

同时 Swagger 除了接口文档功能外，还提供了接口调试功能，以建立用户接口为例，单击建立用户接口，能够看到接口定义的参数、返回值、响应码等，单击 Try it out 按钮，而后点击 Execute 就能够发起调用请求、建立用户，以下图所示：

注解介绍

因为 Swagger 2 提供了很是多的注解供开发使用，这里列举一些比较经常使用的注解。

@Api

@Api 用在接口文档资源类上，用于标记当前类为 Swagger 的文档资源，其中含有几个经常使用属性：

• value：定义当前接口文档的名称。
• description：用于定义当前接口文档的介绍。
• tag：能够使用多个名称来定义文档，但若同时存在 tag 属性和 value 属性，则 value 属性会失效。
• hidden：若是值为 true，就会隐藏文档。

@ApiOperation

@ApiOperation 用在接口文档的方法上，主要用来注解接口，其中包含几个经常使用属性：

• value：对API的简短描述。
• note：API的有关细节描述。
• esponse：接口的返回类型（注意：这里不是返回实际响应，而是返回对象的实际结果）。
• hidden：若是值为 true，就会在文档中隐藏。

@ApiResponse、@ApiResponses

@ApiResponses 和 @ApiResponse 两者配合使用返回 HTTP 状态码。@ApiResponses 的 value 值是 @ApiResponse 的集合，多个 @ApiResponse 用逗号分隔，其中 @ApiResponse 包含的属性以下：

• code：HTTP状态码。
• message：HTTP状态信息。
• responseHeaders：HTTP 响应头。

@ApiParam

@ApiParam 用于方法的参数，其中包含如下几个经常使用属性：

• name：参数的名称。
• value：参数值。
• required：若是值为 true，就是必传字段。
• defaultValue：参数的默认值。
• type：参数的类型。
• hidden：若是值为 true，就隐藏这个参数。

@ApiImplicitParam、@ApiImplicitParams

两者配合使用在 API 方法上，@ApiImplicitParams 的子集是 @ApiImplicitParam 注解，其中 @ApiImplicitParam 注解包含如下几个参数：

• name：参数的名称。
• value：参数值。
• required：若是值为 true，就是必传字段。
• defaultValue：参数的默认值。
• dataType：数据的类型。
• hidden：若是值为 true，就隐藏这个参数。
• allowMultiple：是否容许重复。

@ResponseHeader

API 文档的响应头，若是须要设置响应头，就将 @ResponseHeader 设置到 @ApiResponse 的 responseHeaders 参数中。@ResponseHeader 提供了如下几个参数：

• name：响应头名称。
• description：响应头备注。

@ApiModel

设置 API 响应的实体类，用做 API 返回对象。@ApiModel 提供了如下几个参数：

• value：实体类名称。
• description：实体类描述。
• subTypes：子类的类型。

@ApiModelProperty

设置 API 响应实体的属性，其中包含如下几个参数：

• name：属性名称。
• value：属性值。
• notes：属性的注释。
• dataType：数据的类型。
• required：若是值为 true，就必须传入这个字段。
• hidden：若是值为 true，就隐藏这个字段。
• readOnly：若是值为 true，字段就是只读的。
• allowEmptyValue：若是为 true，就容许为空值。

到此为止，咱们就介绍完了 Swagger 提供的主要注解。

总结

Swagger 能够轻松地整合到 Spring Boot 中构建出强大的 RESTful API 文档，能够减小咱们编写接口文档的工做量，同时接口的说明内容也整合入代码中，可让咱们在修改代码逻辑的同时方便的修改接口文档说明，另外 Swagger 也提供了页面测试功能来调试每一个 RESTful API。

若是项目中还未使用，不防尝试一下，会发现效率会提高很多。

本文的完整代码在 https://github.com/wupeixuan/... 的 interface-doc 目录下。

最好的关系就是互相成就，你们的在看、转发、留言三连就是我创做的最大动力。

参考

http://swagger.io

https://github.com/wupeixuan/...

《Spring Boot 2 实战之旅》