refactor(catalog): split OpenAPI spec into per-plugin files with independent generation#2735
Merged
google-oss-prow[bot] merged 6 commits intoMay 26, 2026
Conversation
Restructure the monolithic catalog.yaml source into per-plugin specs so each plugin can independently define its own API paths and schemas while sharing common types from common.yaml. - Slim api/openapi/src/catalog.yaml to core (sources, labels, preview) - Add catalog/plugins/model/api/openapi/ (model paths + schemas) - Add catalog/plugins/mcp/api/openapi/ (MCP paths + schemas) - Add scripts/merge_catalog_specs.sh to combine core + plugins + lib - Update Makefile to use merge_catalog_specs.sh for catalog.yaml The merged output is semantically identical to the previous monolithic spec — generated code, validation, and tests are unchanged. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Alessio Pragliola <seth.pro@gmail.com>
Generate server stubs (controllers, interfaces) per-plugin instead of
from the unified spec, while keeping client models in catalog/pkg/openapi/.
- Add scripts/assemble_plugin_spec.sh to build standalone specs per plugin
- Add catalog/plugins/{model,mcp}/scripts/gen_openapi_server.sh for
independent per-plugin code generation
- Add per-plugin .openapi-generator-ignore files
- Split api.go into api_model.go + api_mcp.go (same package, no breaking change)
- Refactor catalog/scripts/gen_openapi_server.sh into orchestrator
- Update catalog/Makefile with per-plugin targets and dependency isolation
Changing a plugin's spec only regenerates that plugin's controller.
Generated output is identical to the previous unified generation.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: Alessio Pragliola <seth.pro@gmail.com>
Co-locate plugin specs with other OpenAPI sources under api/openapi/src/ instead of catalog/plugins/*/api/openapi/. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Alessio Pragliola <seth.pro@gmail.com>
Flatten per-plugin directory structure (openapi.yaml + components.yaml) into single files (model.yaml, mcp.yaml) under api/openapi/src/plugins/. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Alessio Pragliola <seth.pro@gmail.com>
Regenerate .gitattributes to reflect api.go → api_model.go/api_mcp.go rename. Fix clean-internal-server-openapi to also delete per-plugin output files so both plugins regenerate after a clean. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Alessio Pragliola <seth.pro@gmail.com>
Clean up README.md, api/openapi.yaml, and .openapi-generator-ignore after each plugin generation run to prevent untracked files in CI. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Alessio Pragliola <seth.pro@gmail.com>
Contributor
Author
|
/approve |
Contributor
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: Al-Pragliola The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
model.yaml,mcp.yaml) underapi/openapi/src/plugins/, keeping onlycore endpoints (sources, labels, preview) in
catalog.yamlin
catalog/pkg/openapi/scripts/assemble_plugin_spec.shto build standalone specs per plugin andscripts/merge_catalog_specs.shto produce the unifiedcatalog.yamlMotivation
The monolithic
catalog.yamlsource made it difficult to reason about plugin boundaries — adding or modifying a plugin's API required editinga single large file shared across all plugins. Splitting specs per-plugin:
<name>.yamlinapi/openapi/src/plugins/and add a generation scriptKey changes
api/openapi/src/plugins/model.yamlapi/openapi/src/plugins/mcp.yamlapi/openapi/src/catalog.yamlscripts/merge_catalog_specs.shapi/openapi/catalog.yamlscripts/assemble_plugin_spec.shcatalog/plugins/*/scripts/gen_openapi_server.shcatalog/MakefileVerification
api/openapi/catalog.yamlis byte-identical before and after (verified via diff)make api/openapi/catalog.yamlregenerates correctlymake -C catalog gen/openapi-servergenerates both plugin stubs successfullygo build ./...incatalog/compiles cleanlyHow Has This Been Tested?
catalog.yamlmatches previous output (no semantic changes)Merge criteria:
DCOcheck)ok-to-testhas been added to the PR.