记录

Swagger2学习

  • 2022-04-25
  • 作者 我爱小小蝶
  • ~4.42K 字
  1. 1. 一、常用注解
  2. 2. 二、 依赖
  3. 3. 三、 配置类SwaggerConfig
  4. 4. 四、 实体配置
  5. 5. 五、拓展：其他皮肤

springboot 2.6 版本以上的要在配置文件(yml/ properties)里添加下面的配置信息

1
2
3
spring:  mvc:
	pathmatch:      
		matching-strategy: ANT_PATH_MATCHER

一、常用注解

Swagger的所有注解定义在io.swagger.annotations包下

下面列一些经常用到的，未列举出来的可以另行查阅说明：

Swagger注解 简单说明
@Api(tags = “xxx模块说明”) 作用在模块类上
@ApiOperation(“xxx接口说明”) 作用在接口方法上
@ApiModel(“xxxPOJO说明”) 作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true) 作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”) 作用在参数、方法和字段上，类似@ApiModelProperty

二、 依赖

1
2
3
4
5
6
7
8
9
10
11
<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>

三、 配置类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
31
32
33
34
35
36
37
@Configuration
@EnableSwagger2  // 开启Swagger2
public class SwaggerConfig {

    // 配置docket以配置Swagger具体参数
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                .groupName("hello") // 配置分组
                .select()
                // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                // any() 扫描所有，项目中的所有接口都会被扫描到
                // none()不扫描接口
                // withMethodAnnotation(final Class<? extends Annotation> annotation)通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求

                // basePackage(final String basePackage) 根据包路径扫描接口
                .build();
    }

    // 配置文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("蓝", "https://lan-wa.github.io/", "1584476784@qq.com");
        return new ApiInfo(
                "SwaggerAPI文档", // 标题
                "即使在小的帆也能远航", // 描述
                "v1.0", // 版本
                "https://lan-wa.github.io/", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "", // 许可连接
                new ArrayList<>()// 扩展
        );
    }

}

四、 实体配置

1、新建一个实体类：

1
2
3
4
5
6
7
@ApiModel("用户实体")
public class User {
   @ApiModelProperty("用户名")
   public String username;
   @ApiModelProperty("密码")
   public String password;
}

2 、只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：

1
2
3
4
@RequestMapping("/getUser")
public User getUser(){
   return new User();
}

注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。

@ApiModel为类添加注释

@ApiModelProperty为类属性添加注释

我们也可以给请求的接口配置一些注释

1
2
3
4
5
6
@ApiOperation("**的接口")
@PostMapping("/user")
@ResponseBody
public String kuang(@ApiParam("这个名字会被返回")String username){
   return username;
}

这样的话，可以给一些比较难理解的属性或者接口，增加一些配置信息，让人更容易阅读！

相较于传统的Postman或Curl方式测试接口，使用swagger简直就是傻瓜式操作，不需要额外说明文档(写得好本身就是文档)而且更不容易出错，只需要录入数据然后点击Execute，如果再配合自动化框架，可以说基本就不需要人为操作了。

缺点：在正式环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运行时内存。

重启项目，访问测试 http://localhost:8081/swagger-ui.html 看下效果；

五、拓展：其他皮肤

我们可以导入不同的包实现不同的皮肤定义：

1、默认的 访问 http://localhost:8080/swagger-ui.html

1
2
3
4
5
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

2、bootstrap-ui 访问 http://localhost:8080/doc.html

1
2
3
4
5
6
<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

3、Layui-ui 访问 http://localhost:8080/docs.html

1
2
3
4
5
6
<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>

4、mg-ui 访问 http://localhost:8080/document.html

1
2
3
4
5
6
<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>