Jtoss
Jason
目录

SpringBoot - 接口文档之Swagger

# SpringBoot - 接口文档之Swagger

# Swagger介绍

# 为什么要用Swagger？

作为一名程序员，我们最讨厌两件事：1. 别人不写注释。2. 自己写注释。

而作为一名接口开发者，我们同样讨厌两件事：1. 别人不写接口文档，文档不及时更新。2. 需要自己写接口文档，还需要及时更新。

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。

而随着Springboot、Springcloud等微服务的流行，每个项目都有成百上千个接口调用，这时候再要求人工编写接口文档并且保证文档的实时更新几乎是一件不可能完成的事，所以这时候我们迫切需要一个工具，一个能帮我们自动化生成接口文档以及自动更新文档的工具。它就是Swagger。

Swagger 提供了一个全新的维护 API 文档的方式，有4大优点：

  1. 自动生成文档：只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。
  2. 跨语言性，支持 40 多种语言。
  3. Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。
  4. 还可以将文档规范导入相关的工具（例如 SoapUI）, 这些工具将会为我们自动地创建自动化测试。

Swagger3完全遵循了 OpenAPI 规范。Swagger 官网地址：https://swagger.io/ (opens new window)。

# Swagger和SpringFox有啥关系？

Swagger 可以看作是一个遵循了 OpenAPI 规范的一项技术，而 springfox 则是这项技术的具体实现。 就好比 Spring 中的 IOC 和 DI 的关系 一样，前者是思想，而后者是实现。

# Knife4J和Swagger什么关系？

本质是Swagger的增强解决方案，前身只是一个SwaggerUI（swagger-bootstrap-ui）

Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案, 前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!

Knife4j的前身是swagger-bootstrap-ui，为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j

更名后主要专注的方面

  • 前后端Java代码以及前端Ui模块进行分离,在微服务架构下使用更加灵活
  • 提供专注于Swagger的增强解决方案,不同于只是改善增强前端Ui部分

相关文档请参考：https://doc.xiaominfo.com/knife4j/documentation/

现在我们知道了Swagger的作用，接下来将其集成到我们项目中。

# Swagger集成

这里使用Swagger3，官方文档总结Swagger3的改动如下几点：

集成Swagger很简单，只需要简单三步。

# 第一步： 引入依赖包

引入springfox依赖包，最新的是3.x.x版本。和之前的版本比，只需要引入如下的starter包即可。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
1
2
3
4
5

# 第二步：修改配置文件

  1. application.yml 加入配置

    通常情况下swagger只能在开发环境或测试环境下开启，生产环境下需要进行关闭的。而swagger的开启与关闭可在application.properties中进行配置：

    # 生产环境需设置为false
springfox:
  documentation:
    swagger-ui:
      enabled: true
    1
    2
    3
    4
    5

  2. 增加一个swagger配置类

    /**
 * @author jason
 */
@Configuration
@EnableOpenApi
public class SwaggerConfig {
    /**
     * @return swagger config
     */
    @Bean
    public Docket openApi() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("Test group")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .globalRequestParameters(getGlobalRequestParameters())
                .globalResponses(HttpMethod.GET, getGlobalResponseMessage())
                .globalResponses(HttpMethod.POST, getGlobalResponseMessage());
    }

    /**
     * @return global request parameters
     */
    private List<RequestParameter> getGlobalRequestParameters() {
        List<RequestParameter> parameters = new ArrayList<>();
        parameters.add(new RequestParameterBuilder()
                .name("uuid")
                .description("设备uuid")
                .required(true)
                .in(ParameterType.QUERY)
                .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
                .required(false)
                .build());
        return parameters;
    }

    private List<Response> getGlobalResponseMessage() {
        List<Response> responseList = new ArrayList<>();
        responseList.add(new ResponseBuilder().code("404").description("未找到资源").build());
        return responseList;
    }

    /**
     * @return api info
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger API")
                .description("test api")
                .contact(new Contact("jason", "https://blog.jtoss.cn", "hengweno@163.com"))
                .termsOfServiceUrl("http://xxxxxx.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
    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

    这里通过 .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))表面给加上 @Api注解的类自动生成接口文档。

# 第三步，配置API接口

/**
 * @author jason
 */
@Slf4j
@RestController
@Validated
@Api(tags = "参数校验")
public class DemoController {
    @ApiOperation("添加接口")
    @PostMapping(value = "/valid/add")
    public String add(@Validated(value = ValidGroup.Crud.Create.class) ValidVO validVO){
        log.info("validEntity is {}", validVO);
        return "test3 valid success";
    }

    @ApiOperation("更新接口")
    @PostMapping(value = "/valid/update")
    public String update(@Validated(value = ValidGroup.Crud.Update.class) ValidVO validVO){
        log.info("validEntity is {}", validVO);
        return "test4 valid success";
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

通过 @Api注解标注需要生成接口文档，通过 @ApiOperation注解标注接口名。同时我们给 ValidVO也加上对应的注解:

/**
 * @author jason
 */
@Data
public class ValidVO {
    @ApiModelProperty("ID")
    @Null(groups = ValidGroup.Crud.Create.class)
    @NotNull(groups = ValidGroup.Crud.Update.class, message = "ID不能为空")
    private String id;

    @ApiModelProperty(value = "应用ID",example = "cloud")
    @Null(groups = ValidGroup.Crud.Create.class)
    @NotNull(groups = ValidGroup.Crud.Update.class, message = "应用ID不能为空")
    @Length(groups = ValidGroup.Crud.Update.class, min = 6, max = 12, message = "appId长度必须位于6到12之间")
    private String appId;

    @ApiModelProperty(value = "名字")
    @NotBlank(groups = ValidGroup.Crud.Create.class, message = "名字为必填项")
    private String name;

    @ApiModelProperty(value = "邮箱")
    @Email(message = "请填写正确的邮箱地址")
    private String email;

    @ApiModelProperty(value = "性别")
    @EnumString(value = {"F", "M"}, message = "性别只允许为F或M")
    private String sex;

    @ApiModelProperty(value = "级别")
    @NotEmpty(message = "级别不能为空")
    private String level;
}
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

# 展示效果

启动SpringBoot项目，访问地址：http://127.0.0.1:8095/swagger-ui/index.html

springboot-swagger1

# Swagger3注解使用说明

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性
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

# 导出离线文档

Swagger为我们提供了方便的在线文档支持，但某些场景下我们需要把接口文档提供给合作人员，而不是直接给一个地址。此时，我们就需要将接口文档导出为离线文档。

这里我们集成增强文档knife4j来实现离线文档的导出。

# 第一步：添加依赖

在pom.xml中增加knife4j的依赖：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>
1
2
3
4
5

# 第二步：修改配置

在上面配置Swagger的SwaggerConfig中添加@EnableKnife4j注解，该注解可以开启knife4j的增强功能。

/**
 * @author jason
 */
@Configuration
@EnableOpenApi
@EnableKnife4j
public class SwaggerConfig {
	....
}
1
2
3
4
5
6
7
8
9

此时，如果依旧访问http://localhost:8095/swagger-ui/index.html (opens new window) 会发现显示并没有变化。这里我们需要访问http://localhost:8095/doc.html。 (opens new window)

# 展示效果

springboot-swagger2

# 示例源码

https://github.com/hengwen/spring-demo/tree/main/springbootswagger

#Spring Boot#Swagger
上次更新: 2024-08-19
SpringBoot - 接口参数校验
SpringBoot - 接口文档之Smart-Doc

← SpringBoot - 接口文档之Smart-Doc→

最近更新
01
开始
01-09
02
AI工具分享
01-09
03
AI 导读
01-07
更多文章>
Theme by Vdoing | Copyright © 2022-2025 Jason Huang | 闽ICP备2025088096号-1