超详细 Swagger 使用指南（附带注解总结和源码）

1. Swagger 简介

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTfu风格的web服务。目标是使客户端和文件系统作为服务器一同样的速度来更新文件的方法，参数和模型紧密集成到服务器。这个解释简单点来讲就是说，swagger是一款可以根据restful风格生成的接口开发文档，并且支持做测试的一款中间软件。

依赖坐标

• Springfox Swagger UI

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

• Springfox Swagger2

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

2. 工程目录及环境介绍

2.1 工程目录

2.2 环境介绍

• 操作系统：macOS Catalina 10.15.3
• IDEA：IntelliJ IDEA 2019.1 (Ultimate Edition)
• JDK：1.8
• SpringBoot：2.2.6RELEASE
• Swagger UI：2.9.2
• Swagger2：2.9.2

3. SpringBoot 集成 Swagger

3.1 新建 SpringBoot 的 Web 项目

3.2 导入上述2个依赖

<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>

3.3 开启 Swagger

• 新建一个 SwaggerConfig 类

• 添加 @Configuration:表明这是一个配置类

• 开启 Swagger2

@Configuration  //表明这是一个注解类
@EnableSwagger2  //开启 Swagger2
public class SwaggerConfig {

}

3.4 测试 Swagger2 是否启动成功

• 访问：http://localhost:8089/swagger-ui.html

4. 配置 Swagger 信息

4.1 编写配置类

package com.kuang.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
import java.util.ArrayList;

/**
 * @author Hedon Wang
 * @create 2020-06-23 20:23
 */

@Configuration  //表明这是一个注解类
@EnableSwagger2  //开启 Swagger2
public class SwaggerConfig {

    /**
     * 配置 Swagger 的 Docket 的 Bean 实例
     * @return
     */
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置 Swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("Hedon","http://hedon.wang","171725713@qq.com");

        return new ApiInfo("Swagger API 文档",                    //文档标题
                "这个是一个 Swagger 接口文档。",              //文档描述
                "v1.0",                                       //文档版本
                "http://heon.wang",                   //队伍的网站地址
                contact,                                              //作者信息
                "Apache 2.0",                                  //许可证
                "http://www.apache.org/licenses/LICENSE-2.0",//许可证Url
                new ArrayList());
    }

}

4.2 效果

5. 配置扫描接口

在 SwaggerConfig 中对 Docket 对象继续进行设定

• select().apis().paths().build()

/**
 * 配置 Swagger 的 Docket 的 Bean 实例
 * @return
 */
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())  //配置 Swagger ApiInfo 基本信息
            .select()
            /**
             * RequestHandlerSelectors配置要扫描接口的方式
             *          basePackage:指定要扫描的包=>RequestHandlerSelectors.basePackage("com.kuang.swagger.controller")
             *          any():扫描全部
             *          none():全部不扫描
             *          withClassAnnotation:扫描类上的注解=>RequestHandlerSelectors.withClassAnnotation(RestController.class)
             *          withMethodAnnotation:扫描方法上的注解=>RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)
             */
            .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
            /**
             * Path：过滤路径
             *          ant:指定路径
             *          any:过滤全部
             *          none:全部不过滤
             *          regex:按照正则表达式来过滤
             */
            .paths(PathSelectors.ant("/kuang/**"))
            .build();  //工厂模式
}

重新访问：http://localhost:8089/swagger-ui.html

因为我们指定了映射路径为 /kuang/**，所以目前什么接口都没被扫描到

6. 配置是否启动Swagger

• Docket.enable()
• 这里我们设置不启动

6.1 关闭 Swagger

• enable(false)

/**
 * 配置 Swagger 的 Docket 的 Bean 实例
 * @return
 */
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())  //配置 Swagger ApiInfo 基本信息
            .enable(false)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
            .paths(PathSelectors.ant("/kuang/**"))
            .build();  //工厂模式
}

6.2 测试

• 访问 http://localhost:8089/swagger-ui.html

7. 配置 API 文档分组

7.1 配置一个分组

• Docket.groupName()

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())  //配置 Swagger ApiInfo 基本信息
            .groupName("Hedon")
            .enable(true)   //启动
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
            .paths(PathSelectors.ant("/kuang/**"))
            .build();  //工厂模式
}

• 访问： http://localhost:8089/swagger-ui.html

7.2 配置多个分组

• 建立多个 Docket 实例对象

    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("A");
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("B");
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("C");
    }

• 访问： http://localhost:8089/swagger-ui.html

8. 扫描实体类

8.1 新建一个实体类 User

8.2 Controller 中新加一个方法，返回一个 User 对象

• 只要我们的接口中，返回值存在实体类，它就会被扫描到 Swagger 中

@PostMapping("/user")
public User user(){
    return new User("heodn","12345");
}

• 访问： http://localhost:8089/swagger-ui.html

8.3 给实体类添加 API 注释

• @ApiModel

@ApiModel("这是User实体类")
public class User {

8.4 给实体类的属性添加 API 注释

• @ApiModelProperty

@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;

9. 给控制类添加API注解

9.1 接口添加说明注解

• @ApiOpeartion(value=“接口名”,httpMethod=“请求方式”,notes=“详细说明”)

    @GetMapping("/hello")
    @ApiOperation(value = "Hello接口",httpMethod = "GET",notes = "这是Hello接口的详细说明。")
    public String hello(){
        return "hello springboot";
    }

9.2 添加接口参数说明注解

• @ApiImplicitParams 包含多个属性
• @ApiImplicitParam
  • name：属性名
  • value：属性值
  • defaultValue：默认值
  • paramType：表示参数放在哪个地方

    • header–>请求参数的获取：@RequestHeader(代码中接收注解)

    • query–>请求参数的获取：@RequestParam(代码中接收注解)

    • path（用于restful接口）–>请求参数的获取：@PathVariable(代码中接收注解)

    • body–>请求参数的获取：@RequestBody(代码中接收注解)

    • form（不常用，form.serilize()）

  • dataType：参数类型
  • required：是否必须

@GetMapping("/hello")
@ApiOperation(value = "Hello接口",httpMethod = "GET",notes = "这是Hello接口的详细说明。")
@ApiImplicitParams({
        @ApiImplicitParam(name = "username",value = "用户名",defaultValue = "hedon",paramType = "query",dataType="String",required = true),
        @ApiImplicitParam(name = "password",value = "密码",defaultValue = "hedonpassword",paramType = "query",dataType="String",required = true)
})
public String hello(String username,String password){
    return "hello，your username = "+username +" and your password = "+password;
}

10. Swagger 的测试功能

10.1 点击”try it out“

10.2 输入参数

10.3 执行查看结果

11. Swagger 注解总结

11.1 @Api()

• 用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源。

• 参数：

  tags：说明该类的作用，参数是个数组，可以填多个。
  value=“该参数没什么意义，在UI界面上不显示，所以不用配置”
  description = “用户基本信息操作”

11.2 @ApiOperation()

• 用于方法，表示一个http请求访问该方法的操作。

• 参数：

  value=“方法的用途和作用”
  notes=“方法的注意事项和备注”
  tags：说明该方法的作用，参数是个数组，可以填多个。
  格式：tags={“作用1”,“作用2”}
  （在这里建议不使用这个参数，会使界面看上去有点乱，前两个常用）

11.3 @ApiModel()

• 用于响应实体类上，用于说明实体作用。

• 参数：

  description=“描述实体的作用”

11.4 @ApiModelProperty

• 用在属性上，描述实体类的属性

• 参数：

  value=“用户名” 描述参数的意义
  name=“name” 参数的变量名
  required=true 参数是否必选

11.5 @ApiImplicitParams

• 用在请求的方法上，包含多@ApiImplicitParam

11.6 @ApiImplicitParam

• 用于方法，表示单独的请求参数。

• 参数：

  name=“参数ming”

  value=“参数说明”

  dataType=“数据类型”

  paramType=“query” 表示参数放在哪里
  -header–>请求参数的获取：@RequestHeader(代码中接收注解)

  ​ -query–>请求参数的获取：@RequestParam(代码中接收注解)

  ​ -path（用于restful接口）–>请求参数的获取：@PathVariable(代码中接收注解)

  ​ -body–>请求参数的获取：@RequestBody(代码中接收注解)

  ​ -form（不常用，form.serilize()）

  defaultValue=“参数的默认值”

  required=“true” 表示参数是否必须传

11.7 @ApiParam()

• 用于方法，参数，字段说明 表示对参数的要求和说明。

• 参数：

  name=“参数名称”
  value=“参数的简要说明”
  defaultValue=“参数默认值”
  required=“true” 表示属性是否必填，默认为false

11.8 @ApiResponses

• 用于请求的方法上，根据响应码表示不同响应。
• 一个@ApiResponses包含多个@ApiResponse。

11.9 @ApiResponse

• 用在请求的方法上，表示不同的响应。

• 参数：

  code=“404” 表示响应码(int型)，可自定义
  message=“状态码对应的响应信息”

11.10 @ApiIgnore()

• 用于类或者方法上，不被显示在页面上。

11.11 @Profile({“dev”, “test”})

• 用于配置类上，表示只对开发和测试环境有用。

12. 项目源码

12.1 SwaggerDemoApplication.java

package com.kuang.swagger;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class SwaggerDemoApplication {

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

}

12.2 HelloController.java

package com.kuang.swagger.controller;

import com.kuang.swagger.pojo.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author Hedon Wang
 * @create 2020-06-23 20:19
 */

@RestController
public class HelloController {

    @GetMapping("/hello")
    @ApiOperation(value = "Hello接口",httpMethod = "GET",notes = "这是Hello接口的详细说明。")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username",value = "用户名",defaultValue = "hedon",paramType = "query",dataType="String",required = true),
            @ApiImplicitParam(name = "password",value = "密码",defaultValue = "hedonpassword",paramType = "query",dataType="String",required = true)
    })
    public String hello(String username,String password){
        return "hello，your username = "+username +" and your password = "+password;
    }

    //只要我们的接口中，返回值存在实体类，它就会被扫描到 Swagger 中
    @PostMapping("/user")
    public User user(){
        return new User("heodn","12345");
    }
}

12.3 SwaggerConfig.java

package com.kuang.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
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;

import java.util.ArrayList;

/**
 * @author Hedon Wang
 * @create 2020-06-23 20:23
 */

@Configuration  //表明这是一个注解类
@EnableSwagger2  //开启 Swagger2
public class SwaggerConfig {

    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("A");
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("B");
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("C");
    }


    /**
     * 配置 Swagger 的 Docket 的 Bean 实例
     * @return
     */
    @Bean
    public Docket docket(){

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())  //配置 Swagger ApiInfo 基本信息
                .groupName("Hedon")
                .enable(true)   //启动
                .select()
                /**
                 * RequestHandlerSelectors配置要扫描接口的方式
                 *          basePackage:指定要扫描的包=>RequestHandlerSelectors.basePackage("com.kuang.swagger.controller")
                 *          any():扫描全部
                 *          none():全部不扫描
                 *          withClassAnnotation:扫描类上的注解=>RequestHandlerSelectors.withClassAnnotation(RestController.class)
                 *          withMethodAnnotation:扫描方法上的注解=>RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)
                 */
                .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
                /**
                 * Path：过滤路径
                 *          ant:指定路径
                 *          any:过滤全部
                 *          none:全部不过滤
                 *          regex:按照正则表达式来过滤
                 */
                .paths(PathSelectors.ant("/kuang/**"))
                .build();  //工厂模式
    }

    //配置 Swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("Hedon","http://hedon.wang","171725713@qq.com");

        return new ApiInfo("Swagger API 文档",                    //文档标题
                "这个是一个 Swagger 接口文档。",              //文档描述
                "v1.0",                                       //文档版本
                "http://heon.wang",                   //队伍的网站地址
                contact,                                              //作者信息
                "Apache 2.0",                                  //许可证
                "http://www.apache.org/licenses/LICENSE-2.0",//许可证Url
                new ArrayList());
    }

}

12.4 User.java

package com.kuang.swagger.pojo;

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

/**
 * @author Hedon Wang
 * @create 2020-06-23 21:27
 */

@ApiModel("这是User实体类")
public class User {

    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public User() {
    }

    public User(String username, String password) {
        this.username = username;
        this.password = password;
    }

    @Override
    public String toString() {
        return "User{" +
                "username='" + username + '\'' +
                ", password='" + password + '\'' +
                '}';
    }
}

13. 参考资料：

bilibili视频：《狂神说：一小时掌握 Swagger 技术》

知乎：https://zhuanlan.zhihu.com/p/49996147