Spring Boot 集成 Swagger 在线接口文档

Spring Boot 集成 Swagger 在线接口文档

---

1. Swagger 简介

1.1 解决的问题

        随着互联网技术的不断发展，现在的网站架构已经从以前的后端渲染变成了前后端分离。前端和后端的唯一联系变成了 API 接口，因此 API 文档变得越来越重要。但是，由于开发人员需要不断更新代码，开发新接口或更新旧接口，文档往往很难跟得上更新的速度。

        为了解决这个问题，Swagger 成为了一种重要的工具。对于使用接口的人来说，开发人员不需要提供文档，只需要告诉他们一个 Swagger 地址，就可以展示在线的 API 接口文档。此外，调用接口的人员还可以在线测试接口数据。同样地，开发人员在开发接口时，也可以利用 Swagger 进行在线接口文档测试，这给开发人员提供了很大的便利。因此，Swagger 工具变得越来越重要。

1.2 Swagger 官方

        Swagger 是一个用来展示 API 接口文档的工具，它可以帮助开发人员更好地管理和测试接口。要在 Spring Boot 中使用 Swagger 工具，需要导入相应的依赖库，并在项目中配置相关参数。

        在 Swagger 官网 [https://swagger.io/ ↗](https://swagger.io/) 上可以找到相关的文档和工具，可以按照官方文档的指引来完成 Swagger 的导入和配置工作。例如，在 Spring Boot 项目中，可以通过在 pom.xml 配置文件中添加相关依赖库来引入 Swagger 工具，然后在项目中使用注解来标记需要展示的接口，Swagger 工具就会自动生成对应的接口文档。

        总的来说，Swagger 工具可以帮助开发人员更好地管理和测试接口，提高开发效率和代码质量。但是，初学者在使用 Swagger 工具时需要仔细阅读官方文档，确保正确地导入和配置工具，避免出现不必要的错误。

2. Swagger 的 maven 依赖

使用 Swagger 工具，必须要导入 maven 依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
</dependency>

3. Swagger 配置

        使用 Swagger 需要进行配置，Spring Boot 中对 Swagger 的配置非常方便，新建一个配置类，Swagger 的配置类上除了添加必要的@Configuration 注解外，还需要添加@EnableOpenApi 注解。

@EnableOpenApi
@Configuration
public class Swagger3Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30) // 使用 Swagger3.0 版本
            .enable(true)// 是否关闭在线文档，生产环境关闭
            .apiInfo(apiInfo()) // 指定构建 api 文档的详细信息的方法
            .select() // 指定要生成 api 接口的包路径，这里把 action 作为包路径，生成 controller 中的所有接口 
            .apis(RequestHandlerSelectors.basePackage("com.yan.action"))
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 只有在方法接口上添加了 ApiOperation 注解
            .paths(PathSelectors.any()).build().globalResponses(HttpMethod.GET, getGlobalResponseMessage())
            .globalResponses(HttpMethod.POST, getGlobalResponseMessage());
    }
    // 生成摘要信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("接口文档") 设置页面标题
            .description("说明信息") 设置接口描述
            .contact(new Contact("cong", "http://baidu.com", "cong@cong.com"))//设置联系方式
            .version("1.0") //设置版本
            .build(); //构建
    }

        在该配置类中已经使用注释详细解释了每个方法的作用了。到此已经配置好 Swagger 了。现在可以测试一下配置有没有生效，启动项目，在浏览器中输入 http://localhost:8080/test/swagger-ui/，即可看到 swagger 的接口页面，说明 Swagger 集成成功。
        对照 Swagger 配置文件中的配置，可以很明确的知道配置类中每个方法的作用。这样就很容易理解和掌握Swagger 中的配置了，也可以看出，其实 Swagger 配置很简单。
        有可能在配置 Swagger 时关不掉，是因为浏览器缓存引起的，清空一下浏览器缓存即可解决问题。

相关配置;

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

4. Swagger 的使用

        

        我们已经成功地配置了 Swagger 工具，并且测试了一下，发现它的功能正常。现在我们可以开始使用 Swagger 工具了，需要学习常用的注解，这些注解可以分别用于实体类、Controller 类以及 Controller 中的方法上。最后，我们可以在 Swagger 工具的页面上查看在线接口文档，并且结合 Controller 中的方法来测试接口数据。这些功能可以帮助我们更好地管理和测试接口，提高开发效率和代码质量。

4.1 实体类注解

@ApiModel(value = "用户实体类")
public class User {

    @ApiModelProperty(value = "用户唯一标识")
    private Long id;

    @ApiModelProperty(value = "用户姓名")
    private String username;

    @ApiModelProperty(value = "用户密码")
    private String password;

    // 省略 set 和 get 方法
}

        这段代码是一个使用了 Swagger 注解的 Java 类。其中，@ApiModel(value = "用户实体类") 注解用于描述该类的作用和含义，即该类是一个用户实体类。@ApiModelProperty 注解用于描述该属性的含义和限制，例如 @ApiModelProperty(value = "用户唯一标识") 描述了 id 属性是用户的唯一标识。同样的，@ApiModelProperty(value = "用户姓名") 和 @ApiModelProperty(value = "用户密码") 分别描述了 username 和 password 属性的含义。

4.2 Controller 类中相关注解

@RestController
@RequestMapping("/swagger")
@Api(value = "Swagger2 在线接口文档")
public class TestController {

    @GetMapping("/get/{id}")
    @ApiOperation(value = "根据用户唯一标识获取用户信息")
    public JsonResult<User> getUserInfo(@PathVariable @ApiParam(value = "用户唯一标识") Long id) {
        // 模拟数据库中根据 id 获取 User 信息
        User user = new User(id, "葱花", "123456");
        return new JsonResult(user);
    }
}

        这段代码是一个使用了 Swagger 注解的 Java 类。其中，@RestController 注解用于将该类声明为一个 RESTful 风格的控制器，@RequestMapping("/swagger") 注解用于设置请求的 URL 前缀。@Api 注解用于描述该类的作用和含义，即该类是用于 Swagger2 在线接口文档的控制器。

        @TestMapping("/get/{id}") 注解用于设置请求的 URL，其中 {id} 表示一个变量。@ApiOperation 注解用于描述该方法的作用和参数。在这个例子中，@ApiOperation(value = "根据用户唯一标识获取用户信息") 描述了 getUserInfo 方法的作用是根据用户唯一标识获取用户信息。@PathVariable 注解用于将 URL 中的变量绑定到方法的参数上，@ApiParam 注解用于描述方法参数的含义和限制。

        在线测试接口：

        localhost:8080/swagger-ui.html 

5. 总结

Spring Boot 集成 Swagger 在线接口文档可以帮助我们更好地管理和测试接口，提高开发效率和代码质量。下面是学习过程中的总结：

1. 引入 Swagger 依赖：在 pom.xml 文件中添加 Swagger 依赖，例如 springfox-swagger2 和 springfox-swagger-ui。

2. 配置 Swagger：在 application.yml 或 application.properties 文件中配置 Swagger 相关属性，例如配置扫描的包路径和 API 文档的标题、描述等。

3. 使用 Swagger 注解：在 Java 类、方法、属性等上使用 Swagger 注解，例如 @Api、@ApiOperation、@ApiModel、@ApiModelProperty 等。这些注解可以帮助 Swagger 工具自动生成准确的接口文档。

4. 启动项目并查看接口文档：启动 Spring Boot 项目，在浏览器中访问 Swagger UI 页面，即可查看在线接口文档。在页面中可以进行接口测试和调试，提高开发效率和代码质量。

总之，Spring Boot 集成 Swagger 在线接口文档是一个非常实用的工具，可以帮助我们更好地管理和测试接口。在使用过程中，我们需要学习相关的注解和配置，并且在使用过程中不断调试和优化，以确保接口文档的准确性和可读性。