knife4j 4.1.0（OpenAPI3）实现spring security或shiro权限注解内容显示

前两天写了个knife4j（swagger2）实现spring security或shiro权限注解内容显示，主要是使用knife4j 2.0.5来实现权限注解内容显示的扩展。

在Spring Boot 3 中只支持OpenAPI3规范，集成knife4j的stater：knife4j-openapi3-jakarta-spring-boot-starter，同时又想实现以上功能时，则可以实现官方提供的GlobalOperationCustomizer接口，从而实现以上功能。

项目使用到哪个权限框架，就用哪个配置就行，能直接使用。

1 Spring Security 注解展示

将Spring Security的PostAuthorize、PostFilter、PreAuthorize、PreFilter的注解信息追加到接口描述中.

import io.swagger.v3.oas.models.Operation;
import org.springdoc.core.customizers.GlobalOperationCustomizer;
import org.springframework.core.annotation.AnnotatedElementUtils;
import org.springframework.security.access.prepost.PostAuthorize;
import org.springframework.security.access.prepost.PostFilter;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.security.access.prepost.PreFilter;
import org.springframework.stereotype.Component;
import org.springframework.web.method.HandlerMethod;

import java.util.ArrayList;
import java.util.List;

@Component
public class SecurityOperationCustomizer implements GlobalOperationCustomizer {

    @Override
    public Operation customize(Operation operation, HandlerMethod handlerMethod) {
        StringBuilder notesBuilder = new StringBuilder(operation.getDescription() == null ? "" : operation.getDescription());
        getClassAnnotationNote(notesBuilder, handlerMethod);
        getMethodAnnotationNote(notesBuilder, handlerMethod);
        operation.setDescription(notesBuilder.toString());
        return operation;
    }

    private void getClassAnnotationNote(StringBuilder notesBuilder, HandlerMethod handlerMethod) {
        List<String> values = new ArrayList<>();
        PostAuthorize postAuthorize = AnnotatedElementUtils.findMergedAnnotation(handlerMethod.getBeanType(), PostAuthorize.class);
        if (postAuthorize != null) {
            values.add(postAuthorize.value());
        }
        PostFilter postFilter = AnnotatedElementUtils.findMergedAnnotation(handlerMethod.getBeanType(), PostFilter.class);
        if (postFilter != null) {
            values.add(postFilter.value());
        }
        PreAuthorize preAuthorize = AnnotatedElementUtils.findMergedAnnotation(handlerMethod.getBeanType(), PreAuthorize.class);
        if (preAuthorize != null) {
            values.add(preAuthorize.value());
        }
        PreFilter preFilter = AnnotatedElementUtils.findMergedAnnotation(handlerMethod.getBeanType(), PreFilter.class);
        if (preFilter != null) {
            values.add(preFilter.value());
        }
        if (!values.isEmpty()) {
            notesBuilder.append("<p />").append("class: ").append(String.join("，", values));
        }
    }

    private void getMethodAnnotationNote(StringBuilder notesBuilder, HandlerMethod handlerMethod) {
        List<String> values = new ArrayList<>();
        PostAuthorize postAuthorize = handlerMethod.getMethodAnnotation(PostAuthorize.class);
        if (postAuthorize != null) {
            values.add(postAuthorize.value());
        }
        PostFilter postFilter = handlerMethod.getMethodAnnotation(PostFilter.class);
        if (postFilter != null) {
            values.add(postFilter.value());
        }
        PreAuthorize preAuthorize = handlerMethod.getMethodAnnotation(PreAuthorize.class);
        if (preAuthorize != null) {
            values.add(preAuthorize.value());
        }
        PreFilter preFilter = handlerMethod.getMethodAnnotation(PreFilter.class);
        if (preFilter != null) {
            values.add(preFilter.value());
        }
        if (!values.isEmpty()) {
            notesBuilder.append("<p />").append("method: ").append(String.join("，", values));
        }
    }
}

2 Apache Shiro 注解展示

将Apache Shiro的RequiresRoles、RequiresPermissions的注解信息追加到接口描述中.

import io.swagger.v3.oas.models.Operation;
import org.apache.shiro.authz.annotation.Logical;
import org.apache.shiro.authz.annotation.RequiresPermissions;
import org.apache.shiro.authz.annotation.RequiresRoles;
import org.springdoc.core.customizers.GlobalOperationCustomizer;
import org.springframework.core.annotation.AnnotatedElementUtils;
import org.springframework.stereotype.Component;
import org.springframework.web.method.HandlerMethod;

import java.util.ArrayList;
import java.util.List;

@Component
public class ShiroOperationCustomizer implements GlobalOperationCustomizer {


    private static final String HTML_P = "<p />";
    private static final String PERM = "权限：";
    private static final String ROLE = "角色：";

    @Override
    public Operation customize(Operation operation, HandlerMethod handlerMethod) {
        StringBuilder notesBuilder = new StringBuilder(operation.getDescription() == null ? "" : operation.getDescription());
        getClassAnnotationNote(notesBuilder, handlerMethod);
        getMethodAnnotationNote(notesBuilder, handlerMethod);
        operation.setDescription(notesBuilder.toString());
        return operation;
    }

    private void getClassAnnotationNote(StringBuilder notesBuilder, HandlerMethod handlerMethod) {
        List<String> values = new ArrayList<>();
        RequiresRoles requiresRoles = AnnotatedElementUtils.findMergedAnnotation(handlerMethod.getBeanType(), RequiresRoles.class);
        if (requiresRoles != null) {
            values.add(HTML_P + ROLE + getAnnotationNote(requiresRoles.value(), requiresRoles.logical()));
        }
        RequiresPermissions requiresPermissions = AnnotatedElementUtils.findMergedAnnotation(handlerMethod.getBeanType(), RequiresPermissions.class);
        if (requiresPermissions != null) {
            values.add(HTML_P + PERM + getAnnotationNote(requiresPermissions.value(), requiresPermissions.logical()));
        }
        if (!values.isEmpty()) {
            notesBuilder.append(HTML_P).append("class: ").append(HTML_P).append(String.join("", values));
        }
    }

    private void getMethodAnnotationNote(StringBuilder notesBuilder, HandlerMethod handlerMethod) {
        List<String> values = new ArrayList<>();
        RequiresRoles requiresRoles = handlerMethod.getMethodAnnotation(RequiresRoles.class);
        if (requiresRoles != null) {
            values.add(HTML_P + ROLE + getAnnotationNote(requiresRoles.value(), requiresRoles.logical()));
        }
        RequiresPermissions requiresPermissions = handlerMethod.getMethodAnnotation(RequiresPermissions.class);
        if (requiresPermissions != null) {
            values.add(HTML_P + PERM + getAnnotationNote(requiresPermissions.value(), requiresPermissions.logical()));
        }
        if (!values.isEmpty()) {
            notesBuilder.append(HTML_P).append("method: ").append(HTML_P).append(String.join("", values));
        }
    }

    private String getAnnotationNote(String[] values, Logical logical) {
        if (logical.equals(Logical.AND)) {
            return String.join(" && ", values);
        } else {
            return String.join(" || ", values);
        }
    }
}

3 Controller演示

3.1 spring security

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.security.access.prepost.PostAuthorize;
import org.springframework.security.access.prepost.PostFilter;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.security.access.prepost.PreFilter;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/swagger")
@Tag(name = "security 注解权限展示")
@PostAuthorize("hasAuthority('class')")
@PostFilter("hasAuthority('class')")
@PreAuthorize("hasAuthority('class')")
@PreFilter("hasAuthority('class')")
public class SecuritySwaggerController {

    @GetMapping("/security")
    @Operation(summary = "security", description = "Spring Security注解追加到接口描述")
    @PostAuthorize("hasAuthority('method')")
    @PostFilter("hasAuthority('method')")
    @PreAuthorize("hasAuthority('method')")
    @PreFilter("hasAuthority('method')")
    public String security() {
        return "hello security";
    }
}

3.2 apache shiro

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.apache.shiro.authz.annotation.Logical;
import org.apache.shiro.authz.annotation.RequiresPermissions;
import org.apache.shiro.authz.annotation.RequiresRoles;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/swagger")
@Tag(name = "shiro 注解权限展示")
@RequiresRoles(value = {"class:role1","class:role2"})
@RequiresPermissions(value = {"class:prem1","class:perm2"}, logical = Logical.OR)
public class ShiroSwaggerController {

    @GetMapping("/shiro")
    @Operation(summary = "shiro", description = "Apache Shiro注解追加到接口描述")
    @RequiresRoles(value = {"method:role1","method:role2"})
    @RequiresPermissions(value = {"method:prem1","method:perm2"}, logical = Logical.OR)
    public String shiro() {
        return "hello shiro";
    }
}

4 效果展示