SpringBoot-(3)使用Swagger生成在线接口文档

Swagger的使用

前言

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

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

1、导入依赖

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.3.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>apidoc-swagger-knife4j</artifactId>

    <dependencies>
        <!-- 实现对 Spring MVC 的自动化配置 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- 1. swagger-bootstrap-ui 目前改名为 knife4j -->
        <!-- 2. 实现 swagger-bootstrap-ui 的自动化配置  -->
        <!-- 3. 因为 knife4j-spring 已经引入 Swagger 依赖，所以无需重复引入 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring</artifactId>
            <version>1.9.6</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-ui</artifactId>
            <version>1.9.6</version>
        </dependency>
    </dependencies>
</project>

2、 SwaggerConfiguration

Spring Boot 暂未提供 Swagger 内置的支持，创建 SwaggerConfiguration 配置类，用于配置 Swagger 。

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2 // 标记项目启用 Swagger API 接口文档
public class SwaggerConfiguration {

    @Bean
    public Docket createRestApi() {
        // 创建 Docket 对象
        return new Docket(DocumentationType.SWAGGER_2) // 文档类型，使用 Swagger2
                .apiInfo(this.apiInfo()) // 设置 API 信息
                // 扫描 Controller 包路径，获得 API 接口
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.iocoder.springboot.lab24.apidoc.controller"))
                .paths(PathSelectors.any())
                // 构建出 Docket 对象
                .build();
    }

    /**
     * 创建 API 信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试接口文档示例")
                .description("我是一段描述")
                .version("1.0.0") // 版本号
                .contact(new Contact("aggtech", "http://www.iocoder.cn", "zhijiantianya@gmail.com")) // 联系人
                .build();
    }
}

3、 Application

创建 Application.java类，配置 @SpringBootApplication 注解即可

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class Application {

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

}

4、UserController

我们创建一个示例，以学习swagger的使用。使用了 Swagger 的注解，所以类和方法上的注释，一般可以删除了。

import cn.iocoder.springboot.lab24.apidoc.dto.UserAddDTO;
import cn.iocoder.springboot.lab24.apidoc.dto.UserUpdateDTO;
import cn.iocoder.springboot.lab24.apidoc.vo.UserVO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;
import java.util.UUID;

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

    @GetMapping("/list")
    @ApiOperation(value = "查询用户列表", notes = "目前仅仅是作为测试，所以返回用户全列表")
    public List<UserVO> list() {
        // 查询列表
        List<UserVO> result = new ArrayList<>();
        result.add(new UserVO().setId(1).setUsername("yudaoyuanma"));
        result.add(new UserVO().setId(2).setUsername("woshiyutou"));
        result.add(new UserVO().setId(3).setUsername("chifanshuijiao"));
        // 返回列表
        return result;
    }

    @GetMapping("/get")
    @ApiOperation("获得指定用户编号的用户")
    @ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024")
    public UserVO get(@RequestParam("id") Integer id) {
        // 查询并返回用户
        return new UserVO().setId(id).setUsername(UUID.randomUUID().toString());
    }

    @PostMapping("add")
    @ApiOperation("添加用户")
    public Integer add(UserAddDTO addDTO) {
        // 插入用户记录，返回编号
        Integer returnId = UUID.randomUUID().hashCode();
        // 返回用户编号
        return returnId;
    }

    @PostMapping("/update")
    @ApiOperation("更新指定用户编号的用户")
    public Boolean update(UserUpdateDTO updateDTO) {
        // 更新用户记录
        Boolean success = true;
        // 返回更新是否成功
        return success;
    }

    @PostMapping("/delete")
    @ApiOperation(value = "删除指定用户编号的用户")
    @ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024")
    public Boolean delete(@RequestParam("id") Integer id) {
        // 删除用户记录
        Boolean success = false;
        // 返回是否更新成功
        return success;
    }

}

5、结果html界面

浏览器访问 http://localhost:8080/doc.html 地址，就可以看到 Swagger 生成的 API 接口文档。

6、常见注解

1 @Api

@Api 注解，添加在 Controller 类上，标记它作为 Swagger 文档资源。

@Api 注解的常用属性，如下：

• tags 属性：用于控制 API 所属的标签列表。[] 数组，可以填写多个。

本质上，tags 就是为了分组 API 接口，和 Controller 本质上是一个目的。所以绝大数场景下，我们只会给一个 Controller 一个唯一的标签。例如说，UserController 的 tags 设置为 "用户 API 接口" 。

2 @ApiOperation

@ApiOperation 注解，添加在 Controller 方法上，标记它是一个 API 操作。

@ApiOperation 注解的常用属性，如下：

• value 属性：API 操作名。
• notes 属性：API 操作的描述。

3 @ApiImplicitParam

@ApiImplicitParam 注解，添加在 Controller 方法上，声明每个请求参数的信息。

@ApiImplicitParam 注解的常用属性，如下：

• name 属性：参数名。
• value 属性：参数的简要说明。
• required 属性：是否为必传参数。默认为 false 。
• dataType 属性：数据类型，通过字符串 String 定义。
• dataTypeClass 属性：数据类型，通过 dataTypeClass 定义。在设置了 dataTypeClass 属性的情况下，会覆盖 dataType 属性。推荐采用这个方式。
• paramType属性：参数所在位置的类型。有如下 5 种方式：
  • "path" 值：对应 SpringMVC 的 @PathVariable 注解。
  • 【默认值】"query" 值：对应 SpringMVC 的 @PathVariable 注解。
  • "body" 值：对应 SpringMVC 的 @RequestBody 注解。
  • "header" 值：对应 SpringMVC 的 @RequestHeader 注解。
  • "form" 值：Form 表单提交，对应 SpringMVC 的 @PathVariable 注解。
  • 😈 绝大多数情况下，使用 "query" 值这个类型即可。
• example 属性：参数值的简单示例。
• examples 属性：参数值的复杂示例，使用 @Example 注解。

需要添加在方法上添加多个 @ApiImplicitParam 注解时，可以使用 @ApiImplicitParams 注解中添加多个。

@ApiImplicitParams({ // 参数数组
        @ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024"), // 参数一
        @ApiImplicitParam(name = "name", value = "昵称", paramType = "query", dataTypeClass = String.class, required = true, example = "芋道"), // 参数二
})

4 @ApiModel

@ApiModel 注解，添加在 POJO 类，声明 POJO 类的信息。

@ApiModel 注解的常用属性，如下：

• value 属性：Model 名字。
• description 属性：Model 描述。

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户添加 DTO")
public class UserAddDTO {
	...
}

5 @ApiModelProperty

@ApiModelProperty 注解，添加在 Model 类的成员变量上，声明每个成员变量的信息。

@ApiModelProperty 注解的常用属性，如下：

• value 属性：属性的描述。
• dataType 属性：和 @ApiImplicitParam 注解的 dataType 属性一致。不过因为 @ApiModelProperty 是添加在成员变量上，可以自动获得成员变量的类型。
• required 属性：和 @ApiImplicitParam 注解的 required 属性一致。
• example 属性：@ApiImplicitParam 注解的 example 属性一致。

6 @ApiResponse

在大多数情况下，我们并不需要使用 @ApiResponse 注解，因为我们会类似 UserController#get(id) 方法这个接口，返回一个 Model 即可。

更多注解请查看http://docs.swagger.io/swagger-core/current/apidocs/index.html