如何在 Spring 端点的 Swagger UI 中显示所需的用户角色(访问控制信息)? [英] How to display required user roles (access control information) in Swagger UI for Spring's endpoints?

问题描述

我有一个在 Spring 中制作的 rest api，并且正在使用 Swagger 来编写文档.最近实施了基于令牌的身份验证.在令牌中，有(内部)用户的角色(权限).每个控制器都用几个 Swagger 注释和一个 @PreAuthorize(some roles..) 注释，如下所示:

I have a rest api made in Spring and am using Swagger for documentation. Recently a token based authentication was implemented. In the token, there are (internal) user's roles (authorities). Each controller is annotated with a couple of Swagger annotations and a @PreAuthorize(some roles..) like so:

@ApiOperation("Delete user")
@ApiResponses(value = {
        @ApiResponse(code = 404, message = "User not found", response = ErrorResponse.class)
})
@PreAuthorize("hasAuthority('ADMIN')")
@DeleteMapping(value = "/{id}")
public ResponseEntity<?> deleteUser(@PathVariable UUID id) {
    userService.delete(id);
    return ResponseEntity.ok().build();
}

现在，我不知道如何在我的 swagger-ui 中显示这些角色，因此每个端点都有信息，需要什么用户角色才能访问它.我浏览了互联网，发现只有一些非常模糊的信息，其中大部分与 Spring 无关.

Now, I have no idea how I can display in my swagger-ui those roles, so each endpoint has information, what user role is required to access it. I have browsed the internet and found only some really vague information, most of it not concerning Spring at all.

注意:我尝试使用 notes: @ApiOperation(value = "Delete user", notes = "Required roles: ADMIN, USER") 来显示自定义文本，但这似乎不是正确的方法.

Note: I tried using notes: @ApiOperation(value = "Delete user", notes = "Required roles: ADMIN, USER") to display custom text, but this doesn't seem like a right way to go.

推荐答案

如果需要保留通过注解添加的现有笔记，并一起添加@Authorisation值，那么做以下..

If you need to keep the existing notes added through annotation and add @Authorisation value together, then do the following..

@ApiOperation(value = "Create new Organisation", notes = "Notes added through annotation")
@Authorization(value = ROOT_ORG_ADMIN)

创建OperationNotesResourcesReader"类如下

create "OperationNotesResourcesReader" class as follows

@Component
@Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER + 1)
@Slf4j
public class OperationNotesResourcesReader implements OperationBuilderPlugin {

private final DescriptionResolver descriptions;

@Autowired
public OperationNotesResourcesReader(DescriptionResolver descriptions) {
    this.descriptions = descriptions;
}

@Override
public void apply(OperationContext context) {
    try {
        Optional<ApiOperation> annotation = context.findAnnotation(ApiOperation.class);
        String notes = (annotation.isPresent() && StringUtils.hasText(annotation.get().notes())) ? (annotation.get().notes()) : "";
        String apiRoleAccessNoteText = "<b>Access Privilieges & Ruels : </b> Nil";
        Optional<PreAuthorize> preAuthorizeAnnotation = context.findAnnotation(PreAuthorize.class);
        if (preAuthorizeAnnotation.isPresent()) {
            apiRoleAccessNoteText = "<b>Access Privilieges & Ruels : </b>" + preAuthorizeAnnotation.get().value();
        }
        notes = apiRoleAccessNoteText + " \n\n " + notes;
        // add the note text to the Swagger UI
        context.operationBuilder().notes(descriptions.resolve(notes));
    } catch (Exception e) {
        LOGGER.error("Error when creating swagger documentation for security roles: " + e);
    }
}

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

注意以下变化

@Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER + 1)

notes = apiRoleAccessNoteText + " \n\n " + notes;
        // add the note text to the Swagger UI
        context.operationBuilder().notes(descriptions.resolve(notes));

这篇关于如何在 Spring 端点的 Swagger UI 中显示所需的用户角色(访问控制信息)?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！