[GH-ISSUE #52] feat: generate the server OpenAPI specification from template file #22

New issue

Closed

opened 2026-10-29 14:18:29 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-29 14:18:29 +00:00

Owner

Originally created by @fy2462 on GitHub (Jul 28, 2026).
Original GitHub issue: https://github.com/kvcache-ai/AgentENV/issues/52

Summary

Replace the manually maintained monolithic src/api/openapi.yml with a small template and tag-based YAML fragments under src/api/spec/.

cargo adev codegen server will first render the fragments into the committed src/api/openapi.yml, then run OpenAPI Generator to update src/api/generated.

The rendered specification remains self-contained and committed to the repository, while the maintainable source is organized by API tag.

src/api/spec/
├── README.md
├── openapi.tmpl
├── components/
│   ├── security.yml
│   ├── parameters.yml
│   ├── responses.yml
│   └── schemas/
│       ├── common.yml
│       ├── admin.yml
│       ├── templates.yml
│       ├── sandboxes.yml
│       └── snapshots.yml
└── paths/
    ├── admin.yml
    ├── templates.yml
    ├── sandboxes.yml
    └── snapshots.yml

Motivation

The server OpenAPI specification is currently maintained as a single src/api/openapi.yml file. As the API grows, this file has become too large to review and maintain safely.

Changes to unrelated API categories are mixed together, shared schemas are hard to distinguish from tag-specific schemas, and merge conflicts become more likely.

Originally created by @fy2462 on GitHub (Jul 28, 2026). Original GitHub issue: https://github.com/kvcache-ai/AgentENV/issues/52 ## Summary Replace the manually maintained monolithic `src/api/openapi.yml` with a small template and tag-based YAML fragments under `src/api/spec/`. cargo adev codegen server will first render the fragments into the committed `src/api/openapi.yml`, then run OpenAPI Generator to update `src/api/generated`. The rendered specification remains self-contained and committed to the repository, while the maintainable source is organized by API tag. ```text src/api/spec/ ├── README.md ├── openapi.tmpl ├── components/ │ ├── security.yml │ ├── parameters.yml │ ├── responses.yml │ └── schemas/ │ ├── common.yml │ ├── admin.yml │ ├── templates.yml │ ├── sandboxes.yml │ └── snapshots.yml └── paths/ ├── admin.yml ├── templates.yml ├── sandboxes.yml └── snapshots.yml ``` ## Motivation The server OpenAPI specification is currently maintained as a single `src/api/openapi.yml` file. As the API grows, this file has become too large to review and maintain safely. Changes to unrelated API categories are mixed together, shared schemas are hard to distinguish from tag-specific schemas, and merge conflicts become more likely.

bsakaguchi closed this issue

2026-10-29 14:18:29 +00:00

bsakaguchi commented

2026-10-29 14:18:30 +00:00

Author

Owner

@LSX-s-Software commented on GitHub (Jul 29, 2026):

Thanks for the proposal. We currently keep the OpenAPI specification as a single document intentionally, because this makes it easier to keep our API definition synchronized with E2B's API documentation.

Splitting the specification would also require us to introduce and maintain additional template-rendering/assembly logic. We do not want to add that complexity solely for the purpose of organizing the OpenAPI document into multiple files.

For now, we would therefore prefer to keep src/api/openapi.yml as the single source of truth.

@LSX-s-Software commented on GitHub (Jul 29, 2026): Thanks for the proposal. We currently keep the OpenAPI specification as a single document intentionally, because this makes it easier to keep our API definition synchronized with E2B's API documentation. Splitting the specification would also require us to introduce and maintain additional template-rendering/assembly logic. We do not want to add that complexity solely for the purpose of organizing the OpenAPI document into multiple files. For now, we would therefore prefer to keep `src/api/openapi.yml` as the single source of truth.

bsakaguchi referenced this issue

2026-10-29 14:18:41 +00:00

[GH-ISSUE #116] install.sh fails on Ubuntu 26.04: no overlaybd release asset for ubuntu1.26.04 #39