BiuBiu

# Swager文档

Swagger 是一套接口文档工具，是一个用于自动生成在线接口文档的框架，并可在线测试接口，可以很好的跟Spring结合，只需要添加少量的代码和注解即可，对于前后端分离的开发者，一份接口文档至关重要...

注解 描述
@Api 标记一个Controller类做为swagger文档资源
@ApiOperation 用在Controller里的方法上
@ApiModel 标记实体对象
@ApiModelProperty 标记实体对象属性
@ApiParam 用于Controller中方法的参数说明，单个参数
@ApiIgnore 用来屏蔽某些接口或参数，使其不在页面上显示

在管理系统里，不想让权限框架拦截swaager，可以放行如下url

swagger: 
  - /v3/api-docs/**
  - /swagger-ui/**
  - /swagger-ui.html
  - /actuator/health
1
2
3
4
5

# 基础介绍

  1. @Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger文档资源。
@Api(value = "页面不显示", tags = {"接口说明", "会在页面中显示", "可配置多个", "页面显示多个"})
@RestController
public class HelloController {
    //TODO
}
1
2
3
4
5
  1. @ApiOperation 用在Controller里的方法上，说明方法的作用
  • value 是该类的简短的叙述
  • nates 是该方法的详细描述。
@PostMapping("/user")
@ApiOperation(value = "添加用户接口", notes = "添加用户接口，参数user")
public String addUser(@RequestBody UserRequest user) {
    //TODO
}
1
2
3
4
5
  1. @ApiImplicitParam 与 @ApiImplicitParams

@ApiImplicitParam 注解用于表明前端传入的name参数的名字

  • required 是否为必需项
  • dataType 参数类型
  • paramType 传递方式 1. query 表示使用url问号的方式传参，这种比较常用 2. form 表示使用formData的方式进行传参
    @ApiImplicitParams 当有多个参数时，需要用@ApiImplicitParams将@ApiImplicitParam包起来
@ApiOperation("添加")
@PutMapping("/add")
@ApiImplicitParams({
    @ApiImplicitParam(name = "name", value = "名字", dataType = "String", required = true),
    @ApiImplicitParam(name = "typeId", value = "类型ID", dataType = "Long", required = true)
})
public String add(String name, Long typeId){
    //TODO
}
1
2
3
4
5
6
7
8
9
  1. @ApiModel：用在类上，表示对类进行说明，用于实体类中的参数接收说明
  2. @ApiModelProperty：用于字段，表示对model属性的说明
@Data
@ApiModel(value = "UserRequest", description = "用户请求参数")
public class UserRequest {

    @ApiModelProperty(value = "用户ID", example = "2", dataType = "Integer", required = true)
    private Integer id;

    @ApiModelProperty(value = "用户姓名", example = "张三")
    private String name;
}
1
2
3
4
5
6
7
8
9
10
  1. @ApiParam 用于Controller中方法的参数说明
@ApiOperation("查询用户名")
@GetMapping("/user")
public String getUser(@ApiParam(name = "uNo" value = "用户编号", required = true) @RequestParam Integer uNo) {
    //TODO
}

@ApiOperation("获取")
@GetMapping("/get")
public String get(@ApiParam(name = "id", value = "数据ID") Long id){
    //TODO
}
1
2
3
4
5
6
7
8
9
10
11

# Swagger2

  1. 添加依赖
<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!--swagger-ui-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
1
2
3
4
5
6
7
8
9
10
11
12
13

可以提取到properties里，如下：

<version>${swagger.version}</version> 

<proerties>
    <swagger-version>2.9.2</swagger-version>
</proerties>
1
2
3
4
5
6
  1. Swagger配置类
package com.biubiu.myboot.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.annotations.ApiIgnore;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

import static springfox.documentation.builders.PathSelectors.regex;

/**
 * <p>
 * 接口文档地址 http://{ip}:{port}/swagger-ui.html
 * </p>
 *
 * @author biubiu
 * @since 2021/11/10
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(true)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(setHeader());
    }

    private Docket docket(String groupName, String title, String pathRegex) {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName(groupName).apiInfo(apiInfo(title))
                .ignoredParameterTypes(ApiIgnore.class)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(regex(pathRegex))
                .build()
                .globalOperationParameters(setHeader());
    }

    private ApiInfo apiInfo(String title) {
        return new ApiInfoBuilder().title(title).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot 测试使用 Swagger2 构建 RestFul APIs")
                //.contact(new Contact("一蓑烟雨任平生", "https://www.baidu.com", "mail@163.com"))
                .description("API 描述")
                .version("1.0")
                .build();
    }

    private List<Parameter> setHeader() {
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();

        String token = "Bearer {jwt}";
        // 声明 key
        tokenPar.name("Token")
                // 文字描述
                .description("jwt令牌")
                // 类型为字符串
                .modelRef(new ModelRef("string"))
                // 参数形式为 header 参数
                .parameterType("header")
                // 默认值
                .defaultValue(token)
                // 是否必须
                .required(false);

        pars.add(tokenPar.build());
        return pars;
    }

}
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
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

配置类控制是否启用Swgger有些生产环境需关闭文档

    // 加开关配置，:true设置默认值
    @Value("${swagger.show:true}")
    private boolean enable;
    docket.enable(enable)
    
    // 根据环境自动切换
    @Value("${spring.profiles.active}") 
    private String activeProfile;   
    docket.enable("dev".equals(activeProfile))

    //还可以这种处理
    docket.paths(PathSelectors.none())
1
2
3
4
5
6
7
8
9
10
11
12

扫描接口的方式配置，还有其他 docket.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) 扫描注解 生成文档 docket.apis(RequestHandlerSelectors.basePackage("com.biubiu.web.controller")) 扫描包 生成文档

# Swagger3

  1. 引入依赖
<!--swagger3-->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>
1
2
3
4
5
6
  1. 配置
/**
 * <p>
 * 接口文档地址 http://{ip}:{port}/swagger-ui/
 * </p>
 *
 * @author biubiu
 * @since 2021/11/10
 */
@Configuration
@EnableOpenApi
public class SwaggerConfig {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    //生成接口信息，包括标题、联系人，联系方式等
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("如有疑问，请联系开发工程师")
                .contact(new Contact("biubiu", "https://baijq.gitee.io/note/", "baijqmail@163.com"))
                .version("1.0")
                .build();
    }
}
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
  1. 配置Token

通过Swagger3中Docket提供的securitySchemes和securityReferences方法进行JWT的配置。效果以及流程如下

@Bean
public Docket docket() {
    return new Docket(DocumentationType.OAS_30)
            .apiInfo(apiInfo())
            // Token
            .securitySchemes(Collections.singletonList(HttpAuthenticationScheme.JWT_BEARER_BUILDER.name("JWT").build()))
            .securityContexts(Collections.singletonList(SecurityContext.builder()
                    .securityReferences(Collections.singletonList(SecurityReference.builder().scopes(new AuthorizationScope[0]).reference("JWT").build()))
                    // 作用域
                    .operationSelector(o -> o.requestMappingPattern().matches("/.*")).build()))
            .select()
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            .paths(PathSelectors.any())
            .build();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

![Oth51P.png

  1. 访问Swagger3 http://{ip}:{port}/swagger-ui/

← Java 技术栈开发工具推荐 →