个人博客
0%

【SpringBoot】Swagger使用

发表于 更新于 分类于

了解Swagger，以及如何在SpringBoot中使用Swagger

一、Swagger的介绍和集成

1.1 Swagger介绍

  • 号称世界上最流行的API框架
  • ResutFul API文档在线自动生成工具 ==> API文档与API定义同步更新
  • 直接运行，可以在线测试API接口
  • 支持多种语言：Java…
  • 官网：https://swagger.io

1.2 集成Swagger

  • （1）导入相应的依赖
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<!--Swagger API接口-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

<!--Swagger UI界面-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

<!--若Swagger为3.0，还需要导入此依赖-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
  • （2）简单创建一个Hello跳转
  • （3）测试

3.0以下版本访问：http://localhost:8080/swagger-ui.html
3.0版本访问：http://localhost:8080/swagger-ui/index.html

会出现以下页面

二、Swagger基础配置

2.1 创建Swagger配置类

1
2
3
4
5
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

}

2.2 注入Docket类

Docket类为配置Swagger中主要配置内容

  • （1）源码分析
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
Docket构造器
public Docket(DocumentationType documentationType) {
    this.apiInfo = ApiInfo.DEFAULT;
    this.groupName = "default";
    this.enabled = true;
    this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
    this.applyDefaultResponseMessages = true;
    this.host = "";
    this.pathMapping = Optional.empty();
    this.apiSelector = ApiSelector.DEFAULT;
    this.enableUrlTemplating = false;
    this.vendorExtensions = new ArrayList();
    this.globalRequestParameters = new ArrayList();
    this.documentationType = documentationType;
} //创建此类要传入一个DocumentationType的参数
                                      
|| 查看Documentation类
						  
public class DocumentationType extends SimplePluginMetadata {
    public static final DocumentationType SWAGGER_12 = new DocumentationType("swagger", "1.2");
    public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0");
    public static final DocumentationType OAS_30 = new DocumentationType("openApi", "3.0");
    /** @deprecated */
    @Deprecated //方法过时
    public static final DocumentationType SPRING_WEB = new DocumentationType("spring-web", "5.2");
    ......
} //Documentation对象，可以直接调用其定义的常量来创建，选择SWAGGER_2
  • （2）修改SwaggerConfig配置类
1
2
3
4
5
6
7
8
9
10
11
12
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

    @Bean
    public Docket getDokcet(Environment environment){
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        //----------------------配置信息-------------------------

        //-----------------------------------------------------------
        return docket;
    }

2.3 修改Swagger信息

调用Docket类中的apiInfo方法

  • （1）源码分析
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
apiInfo方法
public Docket apiInfo(ApiInfo apiInfo) {
    this.apiInfo = (ApiInfo)BuilderDefaults.defaultIfAbsent(apiInfo, this.apiInfo);
    return this;
} //需要传入一个ApiInfo类

         || 查看ApiInfo类

public class ApiInfo {
    public static final Contact DEFAULT_CONTACT = new Contact("", "", "");

    //构造器
    public ApiInfo(String title, String description, String version, String termsOfServiceUrl, Contact contact, String license, String licenseUrl, Collection<VendorExtension> vendorExtensions) {
        this.title = title;
        this.description = description;
        this.version = version;
        this.termsOfServiceUrl = termsOfServiceUrl;
        this.contact = contact;
        this.license = license;
        this.licenseUrl = licenseUrl;
        this.vendorExtensions = new ArrayList(vendorExtensions);
    }
   
    //官方静态构造方法
    static {
        DEFAULT = new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
} //按照官方文档静态代码，参考来设置自定义Swagger信息

Contact类（传参需要的参数之一）
public class Contact {
    //构造器
    public Contact(String name, String url, String email) {
        this.name = name;
        this.url = url;
        this.email = email;
    }
}
  • （2）修改SwaggerConfig配置类
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
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

    @Bean
    public Docket getDokcet(Environment environment){
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        //----------------------配置信息-------------------------
        //配置Swagger信息
        docket.apiInfo(getApiInfo());

        //-----------------------------------------------------------
        return docket;
    }
	
    //创建一个获取ApiInfo对象的方法
    private ApiInfo getApiInfo(){
        //作者信息(姓名，地址，邮箱)
        Contact contact = new Contact("莱特雷", "http://letere.gitee.io/blog", "Xxxx@qq.com");

        return new ApiInfo("letere", //标题
                           "修改的是Swagger信息", //描述
                           "1.0", //版本
                           "urn:tos",
                           contact,
                           "Apache 2.0",
                           "http://www.apache.org/licenses/LICENSE-2.0",
                           new ArrayList());
    };
}
  • 效果如下：

三、配置扫描接口

使用Docket.select()方法类配置

3.1 修改SwaggerConfig配置类

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
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

    @Bean
    public Docket getDokcet(Environment environment){
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        //----------------------配置信息-------------------------
        //配置Swagger信息
        docket.apiInfo(getApiInfo());
		
        //配置扫描接口
            /*
            apis()：要扫描的接口
                RequestHandlerSelectors：配置接口扫描的方式
                    basePackage：扫描的路径（常用）
                    any：扫描全部
                    none：不扫描
                    withClassAnnotation：扫描类上的注解，参数为一个注解的反射对象
                    withMethodAnnotation：扫描方法上的注解
            paths()：过滤扫描接口
            PathSelectors：过滤扫描接口的方式
                    ant：设置路径
             */
        docket.select().apis(RequestHandlerSelectors.basePackage("com.letere.controller")).build(); //扫描此包下的接口

        //-----------------------------------------------------------
        return docket;
    }
}

四、配置开关

实现多环境时，判断是否使用Swagger
一般在开发环境中会使用Swagger，生产环境会关闭Swagger

4.1 方式一：通过Application.yaml设置

在application.yaml中有以下设置来控制Swagger是否开启
可以在不同的环境，选择是否开启

1
2
3
4
springfox:
  documentation:
    swagger-ui:
      enabled: true #开发环境启动swaggger

4.2 方式二：在Docket中设置

可以调用Docket.enable()方法，可以选择开启/关闭Swagger，重点在与如何获取当前的环境，来进行判断

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
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

    @Bean
    public Docket getDokcet(Environment environment){
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        //----------------------配置信息-------------------------
        //配置Swagger信息
        docket.apiInfo(getApiInfo());
		
        //配置扫描接口
        docket.select().apis(RequestHandlerSelectors.basePackage("com.letere.controller")).build(); 
		
        //设置要使用Swagger的环境
        Profiles profiles = Profiles.of("dev"); //可以多参数
        //判断当前环境，是否是要使用Swagger的环境
        boolean b = environment.acceptsProfiles(profiles);
        if (!b){ //如果不是，就关闭Swagger
            docket.enable(false);
        }

        //-----------------------------------------------------------
        return docket;
    }
}

五、添加分组和注释注解

5.1 添加分组

Docket类中使用Docket.group()方法，可以给组起名字
如果需要创建多个分组，只能创建多个Docket类

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
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

    @Bean
    public Docket getDokcet(Environment environment){
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        //----------------------配置信息-------------------------
        //配置Swagger信息
        docket.apiInfo(getApiInfo());
		
        //配置扫描接口
        docket.select().apis(RequestHandlerSelectors.basePackage("com.letere.controller")).build(); 
		
        //设置要使用Swagger的环境
        Profiles profiles = Profiles.of("dev"); //可以多参数
        //判断当前环境，是否是要使用Swagger的环境
        boolean b = environment.acceptsProfiles(profiles);
        if (!b){ 
            docket.enable(false);
        }
		
        //配置分组
        docket.groupName("莱特雷");

        //-----------------------------------------------------------
        return docket;
    }
}

5.2 注释注解

Swagger可以添加注释注解，来给类的方法，属性…添加注释，方便Swagger后台查看

1
2
3
4
5
@ApiModel("用户") //给类添加注释
public class User {
    @ApiModelProperty("用户名") //给类中属性添加注释
    @ApiModelProperty("密码")
    private String password;
1
2
3
4
5
6
7
8
9
@RestController
public class HelloController {

    @ApiOperation("返回用户") //给Controller方法添加注释
    @GetMapping("/user")
    public User user(){
        return new User();
    }
}

5.3 常用注解

  • （1）ApiOperation
1
2
//对接口方法进行解释
@ApiOperation("获取博客文章")
  • （2）ApiImplicitParam 和 ApiImplicitParams
    • ApiImplicitParam对接口的参数进行解释说明
    • 而ApiImplicitParams用于包裹多个ApiImplicitParam
1
2
3
4
5
6
7
8
9
10
11
12
13
14
//ApiImplicitParams使用方法
@ApiImplicitParams({
		@ApiImplicitParam(),
		@ApiImplicitParam()
})


//ApiImplicitParam使用
@ApiImplicitParam(name = "id", value = "博客文章id", dataType = "int", allowMultiple = true, required = true)
// name：参数名
// value: 参数解释说明
// dataType：参数的数据类型：常用有(int, Integer) = int, (String) = string, (Date) = date 【大致上都是数据类型的小写】
// allowMultiple: 是否多个参数，如果参数是数组或集合，需要开启
// requried: 是否必传
  • （3）ApiParam
    • 使用效果和ApiImplicitParam一致，使用的位置直接在参数上
    • 因此可以省略“name”参数名和”dataType”参数数据类型的属性
    • 参数类型为文件（MultipartFile）的只能使用此注解
1
public void test(@ApiParam(value = "文件", required = true) MultipartFile file) {}
  • （4）RequestPart
    • swagger3.x版本，若参数为文件，则需要此注解（2.x版本不需要）
1
public void test(@ApiParam(value = "文件", required = true)  @RequestPart MultipartFile file) {}