我们日常都是基于接口开发项目，一般先试用postman或者其他接口管理工具和前端对好接口。然后双方按照接口开发内容再进行调试。

但是有时候，需要后端自己生成接口文档，那么我们就可以采用Swagger技术，在代码中植入依赖和注解。然后一键生成接口文档，同时可以用于调试和保存。

Swagger对于RestfulAPI风格的接口可以很好的适用。

那么下面我就介绍一下如何在项目中使用Swagger（以SpringBoot项目为例）：

一、引入依赖

    <dependencies>
        <!-- RestfulWeb的依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- Lombok的依赖 -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <!-- Swagger的依赖 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
            <version>4.1.0</version>
        </dependency>
    </dependencies>

二、配置文件

在 [application.yml] 中进行配置

server:
  port: 8080

knife4j:
  enable: true # 开启
  openapi:
    title: 用户管理接口文档
    description: "用户管理接口文档"
    email: 2451203736@qq.com
    concat: 陶其
    url: https://www.tqazy.com
    version: v1.0.0
    group:
      default:
        group-name: default
        api-rule: package
        api-rule-resources:
          - com.tqazy.test_swagger.controller # 扫描Controller所在包地址

三、示例代码

UserController.java

import com.tqazy.test_swagger.domain.dto.UserFormDTO;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

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

    @ApiOperation(value = "新增用户接口", notes = "该方法用于在系统中新增一个用户的信息")
    @PostMapping("/addUser")
    @ApiResponses({
            @ApiResponse(code = 200, message = "新增用户成功"),
            @ApiResponse(code = 500, message = "服务器内部错误")
    })
    public String addUser(@ApiParam("用户表单模型信息") @RequestBody UserFormDTO userDTO) {
        return "演示代码，新增用户成功！";
    }
}

UserFormDTO.java

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

@Data
@ApiModel(value = "用户表单模型", description = "该模型用于新增/修改用户时填写的用户表单信息")
public class UserFormDTO {

    @ApiModelProperty(value = "用户名", example = "蛮吉", required = true)
    private String username;

    @ApiModelProperty(value = "8")
    private String age;

    @ApiModelProperty(value = "用户地址", example = "神圣兽国游尾郡窝窝乡")
    private String address;
}

四、运行测试

启动SpringBoot项目，浏览器访问localhost:8080/doc.html

五、注解使用解析

5.1 控制器类注解

5.1.1 @Api

• 用法： 用于对控制器类进行说明，描述该类的主要功能。
• 参数： value 表示控制器的唯一标识；tags 表示该控制器的标签，用于分组展示。
• 示例：

  @Api("用户管理接口")

• 效果：
  
  

5.2 控制器方法注解

5.2.1 @ApiOperation

• 用法： 用于对控制器中的方法进行说明，描述该方法的功能。
• 参数： value 表示方法的简短描述；notes 表示方法的详细描述。
• 示例代码：

  @ApiOperation(value = "新增用户接口", notes = "该方法用于在系统中新增一个用户的信息")

• 效果：
  
  

5.2.2 @ApiResponses 和 @ApiResponse

• 用法： @ApiResponses 用于批量定义方法的响应信息，@ApiResponse 用于定义单个响应信息，描述方法可能返回的状态码及对应的含义。
• 参数： code 表示状态码；message 表示状态码对应的描述信息。
• 示例代码：

  @ApiResponses({
          @ApiResponse(code = 200, message = "新增用户成功"),
          @ApiResponse(code = 500, message = "服务器内部错误")
  })

• 效果：
  
  

5.3 方法参数注解

5.3.1 @ApiParam

• 用法： 用于对方法的参数进行说明，描述参数的含义、是否必传等信息。
• 参数： value 表示参数的简短描述；required 表示该参数是否必传；example 表示参数的示例值。
• 示例代码：

  @ApiParam("用户表单模型信息")

  效果：
  

  

5.4 模型类注解

5.4.1 @ApiModel

• 用法： 用于对模型类进行说明，描述该类的主要用途。
• 参数： value 表示模型类的唯一标识；description 表示模型类的详细描述。
• 示例代码：

  @ApiModel(value = "用户表单模型", description = "该模型用于新增/修改用户时填写的用户表单信息")

  效果：
  

  

5.4.2 @ApiModelProperty

• 用法： 用于对模型类的属性进行说明，描述属性的含义、示例值等信息。
• 参数： value 表示属性的简短描述；example 表示属性的示例值；required = true 表示属性为必填，默认值：false。
• 示例代码：

  @ApiModelProperty(value = "用户名", example = "蛮吉", required = true)
  private String username;

• 效果：