SpringBoot3 SpringDoc 接口文档模块分组

YouzAi@

已于 2024-08-29 13:59:41 修改

阅读量171

点赞数 7

文章标签： java spring boot

于 2024-08-29 13:57:02 首次发布

本文链接：https://blog.csdn.net/gx18643165/article/details/141676807

版权

1. 配置文件开启springdoc

springdoc:
    api-docs:
        enabled: true

2. 配置springdoc

import io.swagger.v3.oas.annotations.ExternalDocumentation;
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeIn;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import org.springframework.context.annotation.Configuration;

@OpenAPIDefinition(
        info = @Info(
                title = "Swagger 3.0",
                version = "1.0",
                description = "接口文档",
                contact = @Contact(name = "YouZai")
        ),
        security = @SecurityRequirement(name = "JWT"),
        externalDocs = @ExternalDocumentation(description = "参考文档",
                url = "https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations")
)

@SecurityScheme(type = SecuritySchemeType.HTTP, name = "JWT", scheme = "bearer", in = SecuritySchemeIn.HEADER)
@Configuration
public class SpringDocAutoConfiguration {

}

3. controller模块注解

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface ControllerModule {
    /**
     * 模块名称
     *
     * @return 模块名称
     */
    String name() default "";

    /**
     * 描述信息
     *
     * @return 描述信息
     */
    String description() default "";
}

4. 添加controller模块

import com.framework.common.appservice.annotation.AppServiceModule;
import org.springframework.beans.factory.annotation.Configurable;

@Configurable
@ControllerModule(name = "sys", description = "系统管理")
public class SysControllerModule {
}

5. 根据 ContollerModule 自动分组

/**
 * 接口分组配置
 */
@Configuration
@ConditionalOnProperty(name = {"springdoc.api-docs.enabled"}, matchIfMissing = true)
public class DynamicSpringDocAutoConfiguration implements BeanDefinitionRegistryPostProcessor, ApplicationContextAware {

    private ApplicationContext applicationContext;

    @Override
    public void postProcessBeanDefinitionRegistry(BeanDefinitionRegistry registry) throws BeansException {

    }

    @Override
    public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException {
        final DefaultListableBeanFactory defaultListableBeanFactory = (DefaultListableBeanFactory) beanFactory;
        var appServiceModuleBeanMap = applicationContext.getBeansWithAnnotation(ControllerModule.class);
        appServiceModuleBeanMap.forEach((k, v) -> {
            var annotation = v.getClass().getAnnotation(ControllerModule.class);
            var groupedOpenApi = createGroupedOpenApi(StringUtils.hasText(annotation.name())? annotation.name(): k, annotation.description());
            var beanDefinition = BeanDefinitionBuilder.genericBeanDefinition(GroupedOpenApi.class, () -> groupedOpenApi).getBeanDefinition();
            defaultListableBeanFactory.registerBeanDefinition(String.format("%sGroupedOpenApi", groupedOpenApi.getGroup()), beanDefinition);
        });
    }
    /**
     * 生成 GroupedOpenApi
     *
     * @param moduleKey  模块 key
     * @param moduleName 模块名称
     * @return GroupedOpenApi
     */
    private GroupedOpenApi createGroupedOpenApi(String moduleKey, String moduleName) {
        return GroupedOpenApi.builder()
                .group(moduleKey)
                .packagesToScan(String.format("com.framework.controller.%s", moduleKey))
                .pathsToMatch(String.format("/%s/**", moduleKey))
                .displayName(moduleName)
                .addOpenApiCustomizer(getOpenApiCustomizer(moduleName))
                .build();
    }

    private OpenApiCustomizer getOpenApiCustomizer(String moduleName) {
        return openApi -> openApi.info(new Info()
                .title(moduleName)
                .description(String.format("%s API 接口文档", moduleName)));
    }

    @Override
    public void setApplicationContext(ApplicationContext applicationContext) throws BeansException {
        this.applicationContext = applicationContext;
    }
}