springboot（05）整合 Swagger3 生成 API 接口文档

Spring Boot 集成 Swagger3

Swagger是一种开源的API文档工具，它可以自动生成RESTful API文档，让开发者可以更容易地理解和使用API。使用Swagger可以提高开发效率，减少文档编写的工作量，并降低开发者之间的沟通成本。Swagger可以生成各种不同类型的文档，包括HTML、PDF、JSON和XML等。将Swagger与Spring Boot结合使用可以更加方便地生成API文档，并提供实时的API测试功能。使用Swagger可以提高API的可读性和可维护性，使API更易于开发人员和用户使用。

引入依赖

Swagger3 中，我们不需要再引入两个不同的依赖了，我们只需要引入一个依赖就足够，具体引入的依赖如下：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

构建 Swagger 配置类

推荐大家在项目配置文件 application.yml 中添加关于 Swagger 开关的配置，比如这里我添加的配置如下，true 则代表开启 Swagger，false 则表示关闭 Swagger。

spring:
	mvc:
    	pathmatch:
      		matching-strategy: ANT_PATH_MATCHER
swagger:
  enabled: true

配置完成之后，我们就需要在 Swagger 配置类中获取 Swagger 开关的值了，关于具体用法就可以看下边配置代码。

package com.cunyu.springbootswagger3demo.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;



@Configuration
@EnableOpenApi
public class SwaggerConfig {
    /**

   * 用于读取配置文件 application.properties 中 swagger 属性是否开启
     */
         @Value("${swagger.enabled}")
         Boolean swaggerEnabled;
@Bean
public Docket docket() {
    return new Docket(DocumentationType.OAS_30)
            .apiInfo(apiInfo())
            // 是否开启swagger
            .enable(swaggerEnabled)
            .select()
            // 过滤条件，扫描指定路径下的文件
            .apis(RequestHandlerSelectors.basePackage("com.buba.controller"))
            // 指定路径处理，PathSelectors.any()代表不过滤任何路径
            //.paths(PathSelectors.any())
            .build();
}

private ApiInfo apiInfo() {
    /*作者信息*/
    Contact contact = new Contact("XX", "https://baidu.com", "XXX@qq.com");
    return new ApiInfo(
            "Spring Boot 集成 Swagger3 测试",
            "Spring Boot 集成 Swagger3 测试接口文档",
            "v1.0",
            "https://cunyu1943.github.io",
            contact,
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList()
  	  );
	}
}

编写实体类

完成上面的步骤之后，我们的 Swagger 就配置好了，接下来我们就添加一个接口来看看

这里我以一个用户类为实例，带有 name、age 两个属性，也就是本文一开始项目结构截图中 entity 包下的内容。

package com.cunyu.springbootswagger3demo.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;


@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty(value = "姓名", required = true, example = "村雨遥")
    private String name;

    @ApiModelProperty(value = "年龄", required = true, example = "20")
    private Integer age;
}

这里写了两个接口，一个是直接传参，另一种是通过利用创建的 User 实体类来传输，也就是项目结构中 controller 包中的内容。

package com.cunyu.springbootswagger3demo.controller;

import com.cunyu.springbootswagger3demo.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "测试")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation("测试接口1")
    @PostMapping("/show1")
    public String show1(@ApiParam(value = "姓名", required = true, example = "村雨遥") @RequestBody String name) {
        return "hello," + name + ",welcome to springboot swagger3！";
    }

    @ApiOperation("测试接口2")
    @PostMapping("/show2")
    public String show2(@ApiParam(value = "用户对象", required = true) @RequestBody User user) {
        return "hello," + user.getName() + ",welcome to springboot swagger3！";
    }
}

查看并测试接口

启动我们的项目，然后在浏览器中访问如下地址，就可以访问项目的接口文档了。

http://localhost:8080/swagger-ui/index.html

这里也要注意一点，Swagger2 中的接口访问地址是：

http://localhost:8080/swagger-ui.html

Swagger2 和 Swagger3 接口访问地址是不同的。