lingyue-zhibao/backend/lingyue-starter/src/main/java/com/lingyue/config/SpringDocConfig.java

package com.lingyue.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;

/**
 * SpringDoc OpenAPI 配置
 * ⚠️ 仅在 dev 环境启用（双重保障机制）
 *
 * @author lingyue
 */
@Configuration
@Profile("dev")  // 第一层保障：只在 dev profile 时加载
@ConditionalOnProperty(
        name = "springdoc.api-docs.enabled",
        havingValue = "true",
        matchIfMissing = false  // 第二层保障：必须明确启用
)
public class SpringDocConfig {

    @Autowired
    private AppConfig appConfig;

    /**
     * 自定义 OpenAPI 信息
     */
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("灵越智报 API 文档")
                        .description("灵越智报 v2.0 - 智能文档处理平台 API 接口文档<br/>" +
                                "版本: " + appConfig.getVersion() + "<br/>" +
                                "版权所有 © " + appConfig.getCopyrightYear())
                        .version(appConfig.getVersion())
                        .contact(new Contact()
                                .name(appConfig.getName())
                                .email("")))
                ;
    }

    /**
     * 认证服务 API 分组
     */
    @Bean
    public GroupedOpenApi authApi() {
        return GroupedOpenApi.builder()
                .group("auth-api")
                .displayName("认证服务 API")
                .pathsToMatch("/auth/**")
                .build();
    }

    /**
     * 文档管理 API 分组
     */
    @Bean
    public GroupedOpenApi documentApi() {
        return GroupedOpenApi.builder()
                .group("document-api")
                .displayName("文档管理 API")
                .pathsToMatch("/documents/**")
                .build();
    }

    /**
     * 解析服务 API 分组
     */
    @Bean
    public GroupedOpenApi parseApi() {
        return GroupedOpenApi.builder()
                .group("parse-api")
                .displayName("解析服务 API")
                .pathsToMatch("/parse/**")
                .build();
    }

    /**
     * AI处理服务 API 分组
     */
    @Bean
    public GroupedOpenApi aiApi() {
        return GroupedOpenApi.builder()
                .group("ai-api")
                .displayName("AI处理服务 API")
                .pathsToMatch("/ai/**")
                .build();
    }

    /**
     * 关系网络服务 API 分组
     */
    @Bean
    public GroupedOpenApi graphApi() {
        return GroupedOpenApi.builder()
                .group("graph-api")
                .displayName("关系网络服务 API")
                .pathsToMatch("/graphs/**")
                .build();
    }
}