Swagger文档分组校验的正确姿势，后端程序员必备

2023-04-02 22:23:07

引言

随着 API 开发的蓬勃发展，Swagger 文档作为一种流行的工具，为生成 API 文档、测试 API 以及简化 API 开发过程发挥着至关重要的作用。为了进一步提升 API 安全性和开发效率，将 Swagger 文档与后端分组校验相结合是一种有效的方法。本文将深入探究如何利用 Swagger 文档支持后端分组校验，并提供实际示例和常见问题解答。

何为后端分组校验？

后端分组校验是一种安全机制，用于控制 API 的访问权限。它允许您根据用户角色或其他标准将 API 分组，并仅授予特定用户对特定组 API 的访问权限。通过这种方式，您可以限制未经授权的用户访问敏感 API，从而增强应用程序的安全性。

Swagger 文档如何支持后端分组校验？

Swagger 文档通过提供对 API 安全性的配置能力，支持后端分组校验。以下步骤将引导您完成使用 Swagger 文档实现后端分组校验的过程：

1. 安装 Swagger 文档生成器

在您的项目中安装 Swagger 文档生成器，例如 swagger-codegen。

# 使用 Maven 安装
mvn install swagger-codegen-cli -DgroupId=com.github.joelittlejohn -DartifactId=swagger-codegen-cli -Dversion=2.4.21

2. 定义分组校验

在您的控制器中定义分组校验注解，例如 @PreAuthorize("hasRole('ADMIN')")，以控制对特定 API 的访问。

@RestController
@RequestMapping("/api")
public class UserController {

    @PreAuthorize("hasRole('ADMIN')")
    @GetMapping("/users")
    public List<User> getAllUsers() {
        return userService.getAllUsers();
    }

    @PreAuthorize("hasRole('USER')")
    @GetMapping("/users/{id}")
    public User getUserById(@PathVariable Long id) {
        return userService.getUserById(id);
    }
}

3. 配置 Swagger 文档

在 Swagger 文档中配置分组校验注解，例如 @ApiSecurity(name = "bearerAuth")，以关联 Swagger 文档中的安全方案和分组校验。

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .securityContexts(Arrays.asList(securityContext()))
                .securitySchemes(Arrays.asList(apiKey()))
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger API 文档")
                .description("API 文档")
                .version("1.0")
                .build();
    }

    private SecurityContext securityContext() {
        return SecurityContext.builder()
                .securityReferences(Arrays.asList(new SecurityReference("bearerAuth", new AuthorizationScope[]{new AuthorizationScope("global", "")})))
                .build();
    }

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

4. 生成 API 文档

运行 Swagger 文档生成器，生成包含分组校验信息的 API 文档。

java -jar swagger-codegen-cli.jar generate \
  -i /path/to/api-docs \
  -l java \
  -o /path/to/output-directory

代码示例

以下是一个使用 Swagger 文档支持后端分组校验的 Java 示例代码：

@RestController
@RequestMapping("/api")
public class UserController {

    @PreAuthorize("hasRole('ADMIN')")
    @GetMapping("/users")
    public List<User> getAllUsers() {
        return userService.getAllUsers();
    }

    @PreAuthorize("hasRole('USER')")
    @GetMapping("/users/{id}")
    public User getUserById(@PathVariable Long id) {
        return userService.getUserById(id);
    }
}

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .securityContexts(Arrays.asList(securityContext()))
                .securitySchemes(Arrays.asList(apiKey()))
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger API 文档")
                .description("API 文档")
                .version("1.0")
                .build();
    }

    private SecurityContext securityContext() {
        return SecurityContext.builder()
                .securityReferences(Arrays.asList(new SecurityReference("bearerAuth", new AuthorizationScope[]{new AuthorizationScope("global", "")})))
                .build();
    }

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