Springfox Swagger2从入门到精通

概述：Swagger 是一种用于设计、构建、文档化和使用 RESTful API 的工具。Springfox 是 Swagger 在 Spring 应用中的集成库，提供了自动生成 API 文档的功能。在本文中，我们将探讨如何使用 Springfox Swagger2 在 Spring Boot 项目中生成、配置和使用 API 文档

1. 引入依赖

首先，确保在项目的 pom.xml 文件中引入 Springfox Swagger2 的依赖：

<!-- Swagger2 -->
        <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>

2. 配置 Swagger2

在 Spring Boot 项目中，我们需要配置 Swagger2，告诉它在哪里扫描 API，并如何显示文档。创建一个配置类，例如 SwaggerConfig.java：

package org.example.testdoc.config;

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.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.example.testdoc.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Springfox Swagger2 Example")
                .description("This is an example of using Springfox Swagger2 to generate API documentation.")
                .version("1.0")
                .build();
    }
}

在这个配置类中，我们使用 @Configuration 注解标记它为配置类

1. 定义了一个名为api()的方法，该方法返回一个Docket对象，用于配置Swagger。

   • DocumentationType.SWAGGER_2指定了文档类型为Swagger 2。
   • apiInfo()方法用于构建API文档的基本信息，包括标题、描述和版本号。
   • select()方法用于选择要生成文档的API路径和控制器类。
     • apis(RequestHandlerSelectors.basePackage("org.example.testdoc.controller"))指定了扫描的包路径为"org.example.testdoc.controller"，即只扫描该包下的控制器类。
     • paths(PathSelectors.any())表示生成文档包含所有的API路径。
   • build()方法完成构建过程。

2. apiInfo()方法定义了一个私有方法，用于构建API文档的基本信息。

   • ApiInfoBuilder用于构建API文档的信息。
   • title("Springfox Swagger2 Example")设置文档的标题为"Springfox Swagger2 Example"。
   • description("This is an example of using Springfox Swagger2 to generate API documentation.")设置文档的描述信息。
   • version("1.0")设置文档的版本号为"1.0"。
   • build()方法完成构建过程。

编写配置文件：

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

3. 启用 Swagger2

在主应用程序类中使用 @EnableSwagger2 注解启用 Swagger2：

package org.example.testdoc;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class TestdocApplication {

    public static void main(String[] args) {
        SpringApplication.run(TestdocApplication.class, args);
    }

}

现在，当你启动应用程序时，Swagger2 将自动在 http://localhost:8080/swagger-ui.html 上生成 API 文档。

4. 编写 API 文档注释

为了让生成的 API 文档更加详细和清晰，我们需要在控制器类和方法上添加 Swagger2 注解。例如：

package org.example.testdoc.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(value = "Example Controller", tags = "example")
@RestController
public class ExampleController {
    @ApiOperation(value = "Get example data", notes = "This API returns example data.")
    @GetMapping("/example")
    public String getExampleData() {
        return "Hello, World!";
    }
}

1. 使用@Api注解标记该类为API文档的一部分，并设置文档的标题和标签。

   • value = "Example Controller"设置文档的标题为"Example Controller"。
   • tags = "example"设置文档的标签为"example"。

2. 使用@RestController注解将该类标记为RESTful风格的控制器。

3. 定义一个名为getExampleData()的方法，用于处理HTTP GET请求。

   • 使用@ApiOperation注解标记该方法为API文档的一部分，并设置方法的描述信息。
     • value = "Get example data"设置方法的描述为"Get example data"。
     • notes = "This API returns example data."设置方法的备注信息为"This API returns example data."。
   • 使用@GetMapping("/example")注解指定该方法处理的URL路径为"/example"。
   • 方法返回一个字符串"Hello, World!"作为示例数据。

5. 访问 Swagger UI

现在，启动你的 Spring Boot 应用程序，并访问 http://localhost:8080/swagger-ui.html。你将看到生成的 API 文档，可以在此交互式界面中测试和查看你的 API。

6、Springfox Swagger2常用注解分析

@Api：用于标记一个类为API文档的主体，可以设置文档的标题、描述、版本等信息。例如：

@Api(value = "User Controller", description = "Operations pertaining to user")
public class UserController {
    // ...
}

@ApiOperation：用于描述一个方法的操作信息，包括操作的名称、描述、返回值等。例如：

@ApiOperation(value = "Get user by id", notes = "Returns a user")
@GetMapping("/users/{id}")
public User getUserById(@PathVariable Long id) {
    // ...
}

@ApiParam：用于描述一个方法的参数信息，包括参数的名称、描述、数据类型等。例如：

@ApiOperation(value = "Create a new user")
@PostMapping("/users")
public void createUser(@ApiParam(value = "User object", required = true) @RequestBody User user) {
    // ...
}

@ApiModel：用于定义一个模型类，用于描述复杂类型的结构。例如：

@ApiModel(description = "User details")
public class User {
    // ...
}

@ApiModelProperty：用于描述一个模型类的属性信息，包括属性的名称、描述、数据类型等。例如：

@ApiModel(description = "User details")
public class User {
    @ApiModelProperty(value = "The user's name", required = true)
    private String name;
    // ...
}

@ApiResponse：用于描述一个API响应的信息，包括响应的状态码、描述等。例如：

@ApiResponses(value = {
    @ApiResponse(code = 200, message = "Success"),
    @ApiResponse(code = 404, message = "Not found")
})

@ApiIgnore：用于忽略某个API接口或参数，不生成文档。例如：

@ApiIgnore
@GetMapping("/hidden")
public String hiddenEndpoint() {
    // ...
}

@ApiImplicitParam：用于描述一个隐式参数的信息，包括参数的名称、描述、数据类型等。例如：

@ApiOperation(value = "Search users", notes = "Passes the query as a parameter")
@GetMapping("/users/search")
public List<User> searchUsers(@ApiImplicitParam(name = "query", value = "Search query", required = true, dataType = "string") String query) {
    // ...
}

@ApiImplicitParams：用于描述多个隐式参数的信息。例如：

@ApiOperation(value = "Search users", notes = "Passes multiple parameters")
@GetMapping("/users/search")
public List<User> searchUsers(@ApiImplicitParams({
    @ApiImplicitParam(name = "query", value = "Search query", required = true, dataType = "string"),
    @ApiImplicitParam(name = "page", value = "Page number", required = false, dataType = "int")
}) String query, @RequestParam(required = false) Integer page) {
    // ...
}

7. 高级配置

Springfox Swagger2 提供了丰富的配置选项，允许你自定义生成的文档。你可以配置 API 标题、描述、联系信息等。详细配置可以参考 Springfox 文档。

结论

通过集成 Springfox Swagger2，我们可以方便地生成、查看和测试 API 文档。这对于团队协作、前后端协调以及 API 的开发和维护都是非常有益的。希望这篇文章能帮助你入门并更好地利用 Swagger2 在 Spring Boot 项目中管理 API 文档。