From 9a48b8cc1e72e9454c838c3f15ed2aca4bbbb310 Mon Sep 17 00:00:00 2001 From: zichun Date: Thu, 9 Apr 2026 18:01:01 +0800 Subject: [PATCH] feat(bootstrap): group OpenAPI spec by PBC / platform area --- platform/platform-bootstrap/src/main/kotlin/org/vibeerp/platform/bootstrap/openapi/OpenApiConfiguration.kt | 142 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+), 0 deletions(-) diff --git a/platform/platform-bootstrap/src/main/kotlin/org/vibeerp/platform/bootstrap/openapi/OpenApiConfiguration.kt b/platform/platform-bootstrap/src/main/kotlin/org/vibeerp/platform/bootstrap/openapi/OpenApiConfiguration.kt index 199a6f5..1a8b75f 100644 --- a/platform/platform-bootstrap/src/main/kotlin/org/vibeerp/platform/bootstrap/openapi/OpenApiConfiguration.kt +++ b/platform/platform-bootstrap/src/main/kotlin/org/vibeerp/platform/bootstrap/openapi/OpenApiConfiguration.kt @@ -8,6 +8,7 @@ import io.swagger.v3.oas.models.info.License import io.swagger.v3.oas.models.security.SecurityRequirement import io.swagger.v3.oas.models.security.SecurityScheme import io.swagger.v3.oas.models.servers.Server +import org.springdoc.core.models.GroupedOpenApi import org.springframework.beans.factory.ObjectProvider import org.springframework.boot.info.BuildProperties import org.springframework.context.annotation.Bean @@ -126,6 +127,147 @@ class OpenApiConfiguration( ) } + // ─── Grouped specs for the Swagger UI dropdown ─────────────────── + // + // Without explicit groups, springdoc produces ONE giant spec and + // Swagger UI displays 76+ operations in a single unorganized + // list. Grouping by URL prefix gives operators + the future R1 + // SPA a per-PBC filter in Swagger UI's top-right "Select a + // definition" dropdown, and lets clients fetch a focused spec + // via /v3/api-docs/ for codegen against just one + // domain area at a time. + // + // Every group is driven by its URL prefix rather than by package + // scan, because package-scan grouping would force this file (in + // platform-bootstrap) to know every PBC's Kotlin package name + // and re-order whenever a PBC is added. Path-prefix grouping + // only changes when the PBC's @RequestMapping changes — which + // is already a breaking change that would need review anyway. + // + // The primary "all" group (vibeErpOpenApi bean above) stays the + // default at /v3/api-docs. Grouped endpoints serve at + // /v3/api-docs/. + + @Bean + fun platformCoreGroup(): GroupedOpenApi = + GroupedOpenApi.builder() + .group("platform-core") + .displayName("Platform · Core (auth, meta, metadata)") + .pathsToMatch("/api/v1/auth/**", "/api/v1/_meta/**") + .build() + + @Bean + fun platformWorkflowGroup(): GroupedOpenApi = + GroupedOpenApi.builder() + .group("platform-workflow") + .displayName("Platform · Workflow (Flowable BPMN)") + .pathsToMatch("/api/v1/workflow/**") + .build() + + @Bean + fun platformJobsGroup(): GroupedOpenApi = + GroupedOpenApi.builder() + .group("platform-jobs") + .displayName("Platform · Jobs (Quartz)") + .pathsToMatch("/api/v1/jobs/**") + .build() + + @Bean + fun platformFilesGroup(): GroupedOpenApi = + GroupedOpenApi.builder() + .group("platform-files") + .displayName("Platform · Files (object storage)") + .pathsToMatch("/api/v1/files/**") + .build() + + @Bean + fun platformReportsGroup(): GroupedOpenApi = + GroupedOpenApi.builder() + .group("platform-reports") + .displayName("Platform · Reports (JasperReports)") + .pathsToMatch("/api/v1/reports/**") + .build() + + @Bean + fun pbcIdentityGroup(): GroupedOpenApi = + GroupedOpenApi.builder() + .group("pbc-identity") + .displayName("PBC · Identity") + .pathsToMatch("/api/v1/identity/**") + .build() + + @Bean + fun pbcCatalogGroup(): GroupedOpenApi = + GroupedOpenApi.builder() + .group("pbc-catalog") + .displayName("PBC · Catalog (items, UoMs)") + .pathsToMatch("/api/v1/catalog/**") + .build() + + @Bean + fun pbcPartnersGroup(): GroupedOpenApi = + GroupedOpenApi.builder() + .group("pbc-partners") + .displayName("PBC · Partners (customers, suppliers, contacts)") + .pathsToMatch("/api/v1/partners/**") + .build() + + @Bean + fun pbcInventoryGroup(): GroupedOpenApi = + GroupedOpenApi.builder() + .group("pbc-inventory") + .displayName("PBC · Inventory (locations, balances, movements)") + .pathsToMatch("/api/v1/inventory/**") + .build() + + @Bean + fun pbcWarehousingGroup(): GroupedOpenApi = + GroupedOpenApi.builder() + .group("pbc-warehousing") + .displayName("PBC · Warehousing (stock transfers)") + .pathsToMatch("/api/v1/warehousing/**") + .build() + + @Bean + fun pbcOrdersGroup(): GroupedOpenApi = + GroupedOpenApi.builder() + .group("pbc-orders") + .displayName("PBC · Orders (sales + purchase)") + .pathsToMatch("/api/v1/orders/**") + .build() + + @Bean + fun pbcProductionGroup(): GroupedOpenApi = + GroupedOpenApi.builder() + .group("pbc-production") + .displayName("PBC · Production (work orders, routings, shop-floor)") + .pathsToMatch("/api/v1/production/**") + .build() + + @Bean + fun pbcQualityGroup(): GroupedOpenApi = + GroupedOpenApi.builder() + .group("pbc-quality") + .displayName("PBC · Quality (inspection records)") + .pathsToMatch("/api/v1/quality/**") + .build() + + @Bean + fun pbcFinanceGroup(): GroupedOpenApi = + GroupedOpenApi.builder() + .group("pbc-finance") + .displayName("PBC · Finance (journal entries, AR/AP)") + .pathsToMatch("/api/v1/finance/**") + .build() + + @Bean + fun pluginEndpointsGroup(): GroupedOpenApi = + GroupedOpenApi.builder() + .group("plugins") + .displayName("Plug-in HTTP dispatcher") + .pathsToMatch("/api/v1/plugins/**") + .build() + companion object { /** * Name of the security scheme registered in Components. -- libgit2 0.22.2