如何使用 Swagger2 自动生成 RESTful API 文档

如何使用 Swagger2 自动生成 RESTful API 文档

在开发 RESTful API 的过程中，文档是非常重要的一部分。它可以帮助开发者了解 API 的功能和使用方法，同时也是接口设计和测试的重要依据。而手动编写 API 文档往往比较耗时且容易出错，这时候 Swagger2 可以帮我们自动生成 RESTful API 文档。

什么是 Swagger2

Swagger2 是一个开源的 API 文档工具，它可以帮助我们自动生成 RESTful API 文档。Swagger2 定义了一套 API 描述语言（Swagger Definition），可以用来描述 API 的请求和响应参数、接口路径、请求方法、响应状态码等信息。同时，Swagger2 还提供了一个 Web 界面，可以方便地查看和测试 API。

如何使用 Swagger2

1. 引入 Swagger2 依赖

在使用 Swagger2 之前，我们需要先引入它的依赖。在 Maven 项目中，我们可以在 pom.xml 文件中添加以下依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

2. 配置 Swagger2

在引入 Swagger2 依赖之后，我们需要进行一些配置。在 Spring Boot 项目中，我们可以创建一个配置类来配置 Swagger2：

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("Demo API 文档")
            .description("这是一个 Demo 的 API 文档")
            .version("1.0.0")
            .build();
    }
}

上面的代码中，我们首先使用 @Configuration 注解将该类声明为配置类，然后使用 @EnableSwagger2 注解启用 Swagger2。在 api() 方法中，我们创建了一个 Docket 对象，它是 Swagger2 的主要配置对象。我们通过 select() 方法进行 API 选择，使用 RequestHandlerSelectors 来指定 API 的扫描范围，这里我们指定为 com.example.demo.controller 包下的所有类。然后使用 PathSelectors.any() 来指定所有的 URL 都可以进行文档生成功能。最后，我们使用 apiInfo() 方法来设置 API 文档的基本信息，例如文档的标题、描述和版本号等。

3. 测试 Swagger2

在完成 Swagger2 的配置之后，我们可以启动 Spring Boot 应用程序并访问 http://localhost:8080/swagger-ui.html，就可以看到 Swagger2 的 Web 界面了。在这个界面中，我们可以查看 API 的请求和响应参数、接口路径、请求方法、响应状态码等信息，并且可以直接在页面上进行测试。此外，我们还可以将 API 的定义导出为 JSON 或 YAML 格式的文件，以便于进行文档的版本控制和共享。

Swagger2 的高级用法

除了基本的 API 文档生成外，Swagger2 还提供了一些高级用法，例如：

1. API 分组

在实际开发中，我们通常会有多个 API，如果将它们都放在一个文档中，可能会比较混乱。此时，我们可以使用 Swagger2 的 API 分组功能，将不同的 API 分别归为不同的组，方便用户查看。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
   在上面的代码中，我们定义了两个 Docket 对象，分别用于分组名为 v1 和 v2 的 API。在每个 Docket 对象中，我们都通过 `groupName()` 方法指定了分组名称，通过 `select()` 方法指定了 API 的扫描范围。最后，我们通过 `apiInfo()` 方法设置了 API 文档的基本信息。

### 2. API 安全认证

在实际开发中，我们通常会需要对一些敏感的 API 进行安全认证。Swagger2 也提供了相应的功能，可以帮助我们在 API 文档中添加安全认证信息。我们可以通过以下方式来配置 API 安全认证：

```java
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo())
            .securitySchemes(Collections.singletonList(apiKey()))
            .securityContexts(Collections.singletonList(securityContext()));
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("Demo API 文档")
            .description("这是一个 Demo 的 API 文档")
            .version("1.0.0")
            .build();
    }

    private ApiKey apiKey() {
        return new ApiKey("token", "token", "header");
    }

    private SecurityContext securityContext() {
        return SecurityContext.builder()
            .securityReferences(Collections.singletonList(new SecurityReference("token", new AuthorizationScope[]{new AuthorizationScope("global", "accessEverything")})))
            .forPaths(PathSelectors.any())
            .build();
    }
}

上面的代码中，我们通过 securitySchemes() 方法和 securityContexts() 方法分别添加了 API 的安全认证信息。在 securitySchemes() 方法中，我们使用了 ApiKey 对象来定义了一个名为 token 的 API Key，它将被作为 HTTP 请求头的一个自定义字段来传递。在 securityContexts() 方法中，我们使用了 SecurityContext 对象来定义了一个安全上下文，它指定了该 API 的安全认证方式为 token，并且对所有的 URL 都进行了安全认证。

3. API 接口描述

在 Swagger2 中，我们可以通过注解来添加 API 接口的描述信息。例如，在 SpringMVC 中，我们可以使用 @Api、@ApiOperation、@ApiParam 等注解来添加接口的描述信息。例如：

@RestController
@RequestMapping("/users")
@Api(tags = "用户管理")
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping("/{id}")
    @ApiOperation(value = "获取用户", notes = "根据用户 ID 获取用户信息")
    public User getUser(@PathVariable("id") Long id) {
        return userService.getUserById(id);
    }

    @PostMapping
    @ApiOperation(value = "创建用户", notes = "创建新用户")
    public User createUser(@ApiParam(name = "用户对象", value = "需要创建的用户对象") @RequestBody User user) {
        return userService.createUser(user);
    }
}

在上面的代码中，我们在 UserController 类上使用了 @Api 注解来添加了 API 的描述信息，指定了该 API 的标签为“用户管理”。在 getUser() 方法和 createUser() 方法上，我们分别使用了 @ApiOperation 和 @ApiParam 注解来添加了接口的描述信息，例如接口的功能、参数的含义等。

总结

在本文中，我们介绍了如何使用 Swagger2 自动生成 RESTful API 文档。首先，我们引入了 Swagger2 的依赖，并对其进行了基本的配置，然后我们介绍了 Swagger2 的高级用法，包括 API 分组、API 安全认证和 API 接口描述等。通过使用 Swagger2，我们可以方便地生成 API 文档，并且提高了开发效率和文档的准确性。