[PR #53] [CLOSED] feat(api): render server OpenAPI from tag-based templates #142

New issue

Closed

opened 2026-10-29 14:20:08 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:20:08 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/53
Author: @fy2462
Created: 7/28/2026
Status: ❌ Closed

Base: main ← Head: main

📝 Commits (4)

aba229d feat: render server OpenAPI from templates
5b8acb1 chore: remove OpenAPI codegen tests
748e2c1 fix(api): validate spec fragments and field naming
5e56dad Merge remote-tracking branch 'upstream/main'

📊 Changes

19 files changed (+3956 additions, -1437 deletions)

View changed files

📝 Cargo.lock (+10 -0)
📝 adev/Cargo.toml (+1 -0)
📝 adev/src/codegen.rs (+178 -1)
📝 src/api/generated/src/models.rs (+3 -3)
📝 src/api/openapi.yml (+1433 -1433)
➕ src/api/spec/README.md (+80 -0)
➕ src/api/spec/components/parameters.yml (+75 -0)
➕ src/api/spec/components/responses.yml (+37 -0)
➕ src/api/spec/components/schemas/admin.yml (+229 -0)
➕ src/api/spec/components/schemas/common.yml (+35 -0)
➕ src/api/spec/components/schemas/sandboxes.yml (+471 -0)
➕ src/api/spec/components/schemas/snapshots.yml (+47 -0)
➕ src/api/spec/components/schemas/templates.yml (+343 -0)
➕ src/api/spec/components/security.yml (+25 -0)
➕ src/api/spec/openapi.tmpl (+39 -0)
➕ src/api/spec/paths/admin.yml (+59 -0)
➕ src/api/spec/paths/sandboxes.yml (+561 -0)
➕ src/api/spec/paths/snapshots.yml (+74 -0)
➕ src/api/spec/paths/templates.yml (+256 -0)

📄 Description

Summary

Split the monolithic server OpenAPI specification into a template and tag-based YAML fragments under src/api/spec/.

cargo adev codegen server now performs the complete workflow:

Render src/api/openapi.yml from the template and fragments.
Run OpenAPI Generator to update src/api/generated.

The rendered src/api/openapi.yml remains committed to the repository. This keeps it available to documentation and other tooling while making the source specification easier to maintain.

Closes #52

Changes

Add src/api/spec/openapi.tmpl for the top-level OpenAPI document.
Split API paths into tag-based files:
- admin.yml
- templates.yml
- sandboxes.yml
- snapshots.yml
Split schemas into common and tag-owned files.
Move shared error definitions into components/schemas/common.yml.
Extract shared security schemes, parameters, and responses into separate
component files.
Add an OpenAPI renderer to adev/src/codegen.rs.
Add upon as the lightweight template rendering dependency.
Update and commit the rendered src/api/openapi.yml.
Add src/api/spec/README.md describing the rendering rules and API extension
workflow.

Rendering behavior

The renderer reads tag order from the top-level tags section in openapi.tmpl.

The generated document is assembled in the following order:

Top-level metadata and tags from openapi.tmpl.
Shared security schemes, parameters, and responses.
Schemas from components/schemas/common.yml.
Tag-owned schemas in declared tag order.
The health-check endpoint defined directly in the template.
Tag-owned paths in declared tag order.

The position of the tags section within the template does not affect
rendering. Only the order of its entries controls schema and path ordering.

A tag may omit either its schema file or path file. However, a fragment whose
filename does not match a declared tag is rejected to prevent API definitions
from being silently omitted.

Adding an API

For an endpoint under an existing tag:

Update the operation to paths/<tag>.yml.
Update tag-owned models to components/schemas/<tag>.yml.
Add reusable models or errors to components/schemas/common.yml.
Run cargo adev codegen server.

For a new API category:

Add the tag to openapi.tmpl in the desired order.
Add paths/<tag>.yml.
Add components/schemas/<tag>.yml when needed.
Run cargo adev codegen server.

Compatibility

This change reorganizes the source OpenAPI specification without changing its API semantics.

After regeneration, src/api/generated remains unchanged.

No GitHub workflow or documentation build changes are required because the rendered src/api/openapi.yml remains committed.

Validation

Confirmed that src/api/openapi.yml is rendered with the expected formatting
cargo adev codegen server
git diff --check
Confirmed that src/api/generated has no changes
Confirmed that the rendered OpenAPI document is valid with OpenAPI Generator

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/53 **Author:** [@fy2462](https://github.com/fy2462) **Created:** 7/28/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `main` --- ### 📝 Commits (4) - [`aba229d`](https://github.com/kvcache-ai/AgentENV/commit/aba229d255c07b9676d35ff680a67a3a1c2d8952) feat: render server OpenAPI from templates - [`5b8acb1`](https://github.com/kvcache-ai/AgentENV/commit/5b8acb16c0d73e4940041e3dc68a7a43132b2f9a) chore: remove OpenAPI codegen tests - [`748e2c1`](https://github.com/kvcache-ai/AgentENV/commit/748e2c14561b3701428d61714cdc5bd2846d7a58) fix(api): validate spec fragments and field naming - [`5e56dad`](https://github.com/kvcache-ai/AgentENV/commit/5e56dadf38d7116b140c5375a013e81b33a92413) Merge remote-tracking branch 'upstream/main' ### 📊 Changes **19 files changed** (+3956 additions, -1437 deletions) <details> <summary>View changed files</summary> 📝 `Cargo.lock` (+10 -0) 📝 `adev/Cargo.toml` (+1 -0) 📝 `adev/src/codegen.rs` (+178 -1) 📝 `src/api/generated/src/models.rs` (+3 -3) 📝 `src/api/openapi.yml` (+1433 -1433) ➕ `src/api/spec/README.md` (+80 -0) ➕ `src/api/spec/components/parameters.yml` (+75 -0) ➕ `src/api/spec/components/responses.yml` (+37 -0) ➕ `src/api/spec/components/schemas/admin.yml` (+229 -0) ➕ `src/api/spec/components/schemas/common.yml` (+35 -0) ➕ `src/api/spec/components/schemas/sandboxes.yml` (+471 -0) ➕ `src/api/spec/components/schemas/snapshots.yml` (+47 -0) ➕ `src/api/spec/components/schemas/templates.yml` (+343 -0) ➕ `src/api/spec/components/security.yml` (+25 -0) ➕ `src/api/spec/openapi.tmpl` (+39 -0) ➕ `src/api/spec/paths/admin.yml` (+59 -0) ➕ `src/api/spec/paths/sandboxes.yml` (+561 -0) ➕ `src/api/spec/paths/snapshots.yml` (+74 -0) ➕ `src/api/spec/paths/templates.yml` (+256 -0) </details> ### 📄 Description ## Summary Split the monolithic server OpenAPI specification into a template and tag-based YAML fragments under `src/api/spec/`. `cargo adev codegen server` now performs the complete workflow: 1. Render `src/api/openapi.yml` from the template and fragments. 2. Run OpenAPI Generator to update `src/api/generated`. The rendered `src/api/openapi.yml` remains committed to the repository. This keeps it available to documentation and other tooling while making the source specification easier to maintain. Closes #52 ## Changes - Add `src/api/spec/openapi.tmpl` for the top-level OpenAPI document. - Split API paths into tag-based files: - `admin.yml` - `templates.yml` - `sandboxes.yml` - `snapshots.yml` - Split schemas into common and tag-owned files. - Move shared error definitions into `components/schemas/common.yml`. - Extract shared security schemes, parameters, and responses into separate component files. - Add an OpenAPI renderer to `adev/src/codegen.rs`. - Add `upon` as the lightweight template rendering dependency. - Update and commit the rendered `src/api/openapi.yml`. - Add `src/api/spec/README.md` describing the rendering rules and API extension workflow. ## Rendering behavior The renderer reads tag order from the top-level `tags` section in `openapi.tmpl`. The generated document is assembled in the following order: 1. Top-level metadata and tags from `openapi.tmpl`. 2. Shared security schemes, parameters, and responses. 3. Schemas from `components/schemas/common.yml`. 4. Tag-owned schemas in declared tag order. 5. The health-check endpoint defined directly in the template. 6. Tag-owned paths in declared tag order. The position of the `tags` section within the template does not affect rendering. Only the order of its entries controls schema and path ordering. A tag may omit either its schema file or path file. However, a fragment whose filename does not match a declared tag is rejected to prevent API definitions from being silently omitted. ## Adding an API For an endpoint under an existing tag: 1. Update the operation to `paths/<tag>.yml`. 2. Update tag-owned models to `components/schemas/<tag>.yml`. 3. Add reusable models or errors to `components/schemas/common.yml`. 4. Run `cargo adev codegen server`. For a new API category: 1. Add the tag to `openapi.tmpl` in the desired order. 2. Add `paths/<tag>.yml`. 3. Add `components/schemas/<tag>.yml` when needed. 4. Run `cargo adev codegen server`. ## Compatibility This change reorganizes the source OpenAPI specification without changing its API semantics. After regeneration, `src/api/generated` remains unchanged. No GitHub workflow or documentation build changes are required because the rendered `src/api/openapi.yml` remains committed. ## Validation - [x] Confirmed that `src/api/openapi.yml` is rendered with the expected formatting - [x] `cargo adev codegen server` - [x] `git diff --check` - [x] Confirmed that `src/api/generated` has no changes - [x] Confirmed that the rendered OpenAPI document is valid with OpenAPI Generator --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 14:20:08 +00:00