如何根据Java Spring中的当前用户角色修剪Swagger文档？

Question

我正在使用 Spring Boot 开发应用程序，并使用 Swagger 自动生成 API 文档，并且还用于swagger-ui.html与这些 API 进行交互。

我也启用了 Spring Security，并且我有具有不同角色的用户。不同的角色可以使用不同的 REST API。

问题：如何配置 Swagger 以尊重 Spring@Secured显示的注释和修剪操作，swagger-ui.html以便仅对当前用户可用的操作可用？

即想象以下控制器

@RestController
@Secured(ROLE_USER)
public void SomeRestController {
  @GetMapping
  @Secured(ROLE_USER_TOP_MANAGER)
  public String getInfoForTopManager() { /*...*/ }

  @GetMapping
  @Secured(ROLE_USER_MIDDLE_MANAGER)
  public String getInfoForMiddleManager() { /*...*/ }

  @GetMapping
  public String getInfoForAnyUser() { /*...*/ }
}

Swagger 将显示这两种操作getInfoForTopManager，getInfoForMiddleManager无论当前用户角色如何。如果当前经过身份验证的用户角色是ROLE_USER_MIDDLE_MANAGER，我只想在 Swagger 中使用getInfoForMiddleManager和操作。getInfoForAnyUser

Answer 1

好吧，我认为这个问题找到了很好的解决方案。解决方案由 2 部分组成：

1. 扩展控制器扫描逻辑以OperationBuilderPlugin保留 Swagger 供应商扩展中的角色
2. 覆盖ServiceModelToSwagger2MapperImplbean 以根据当前安全上下文过滤掉操作

在您的项目中，这可能看起来有点不同（即很可能您没有类似的东西securityContextResolver），但我相信您将从以下代码中了解此解决方案的要点：

第 1 部分：扩展控制器扫描逻辑以保留 Swagger 供应商扩展中的角色

@Component
@Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER + 1000)
public class OperationBuilderPluginSecuredAware implements OperationBuilderPlugin {
    @Override
    public void apply(OperationContext context) {
        Set<String> roles = new HashSet<>();
        Secured controllerAnnotation = context.findControllerAnnotation(Secured.class).orNull();
        if (controllerAnnotation != null) {
            roles.addAll(List.of(controllerAnnotation.value()));
        }

        Secured methodAnnotation = context.findAnnotation(Secured.class).orNull();
        if (methodAnnotation != null) {
            roles.addAll(List.of(methodAnnotation.value()));
        }

        if (!roles.isEmpty()) {
            context.operationBuilder().extensions(List.of(new TrimToRoles(roles.toArray(new String[0]))));
        }
    }

    @Override
    public boolean supports(DocumentationType delimiter) {
        return SwaggerPluginSupport.pluginDoesApply(delimiter);
    }
}

第 2 部分：根据当前安全上下文过滤掉操作

@Primary
@Component
public class ServiceModelToSwagger2MapperImplEx extends ServiceModelToSwagger2MapperImpl {
    @Autowired
    private SecurityContextResolver<User> securityContextResolver;

    @Override
    protected io.swagger.models.Operation mapOperation(Operation from) {
        if (from == null) {
            return null;
        }
        if (!isPermittedForCurrentUser(findTrimToRolesExtension(from.getVendorExtensions()))) {
            return null;
        }
        return super.mapOperation(from);
    }

    private boolean isPermittedForCurrentUser(TrimToRoles trimToRoles) {
        if (trimToRoles == null) {
            return true;
        }
        if (securityContextResolver.hasAnyRole(trimToRoles.getValue())) {
            return true;
        }
        return false;
    }

    private TrimToRoles findTrimToRolesExtension(@SuppressWarnings("rawtypes") List<VendorExtension> list) {
        if (CollectionUtils.isEmpty(list)) {
            return null;
        }
        return list.stream().filter(x -> x instanceof TrimToRoles).map(TrimToRoles.class::cast).findFirst()
                .orElse(null);
    }

    @Override
    protected Map<String, Path> mapApiListings(Multimap<String, ApiListing> apiListings) {
        Map<String, Path> paths = super.mapApiListings(apiListings);
        return paths.entrySet().stream().filter(x -> !x.getValue().isEmpty())
                .collect(Collectors.toMap(x -> x.getKey(), v -> v.getValue()));
    }

    @Override
    public Swagger mapDocumentation(Documentation from) {
        Swagger ret = super.mapDocumentation(from);
        Predicate<? super Tag> hasAtLeastOneOperation = tag -> ret.getPaths().values().stream()
                .anyMatch(x -> x.getOperations().stream().anyMatch(y -> y.getTags().contains(tag.getName())));
        ret.setTags(ret.getTags().stream().filter(hasAtLeastOneOperation).collect(Collectors.toList()));
        return ret;
    }
}

ps 这些 impl 效率不高，但考虑到它们的使用场景，我更喜欢简单的 impl