docs: update openapi.yml to match CubeAPI implementation#381
docs: update openapi.yml to match CubeAPI implementation#381woshihoujinxin wants to merge 1 commit into
Conversation
woshihoujinxin
requested review from
chenhengqi,
fslongjin,
ls-ggg,
tinklone and
up2wing
as code owners
|
Claude finished @woshihoujinxin's task in 1m 49s —— View job PR Review: docs: update openapi.yml to match CubeAPI implementationopenapi.yml — Overall AssessmentThe OpenAPI spec restructuring looks thorough and well-organized. The diff is large (+1264/-442) but the structure is logical. Here are my observations: ✅ What's done well
|
| Location | Issue |
|---|---|
Sandbox response (connect/create) |
Schema includes envdAccessToken, trafficAccessToken as nullable strings. These are security-sensitive fields — consider noting they're returned only on initial creation/connect. |
/templates/{id}/builds/{bid}/logs |
Only has a 200 response. No 404 (build not found) or 500 error responses, unlike other endpoints. |
/config, /store/meta, /store/refresh |
No error responses at all — only 200. If these endpoints can fail (e.g., store unavailable), they should document error responses. |
SandboxState enum |
enum: [running, paused, pausing] — good addition of pausing state. Consider also adding unknown or error if those states are possible. |
Scope of Changes Outside openapi.yml
The PR title says "update openapi.yml" but 42 other files were also modified. Consider splitting these into separate PRs or updating the PR title/description:
1. SDK model simplification (sdk/python/cubesandbox/)
Significant changes that go beyond a simple documentation update:
__init__.py: SDK version downgraded from0.2.0to0.1.0— this looks like a regression. The openapi.yml version was bumped from0.1.0→0.2.0, but the SDK went backwards. Was this intentional?_models.py: Removedto_json(),formats(),__getitem__,_repr_*_methods,json_dataalias — appears to be removing E2B compatibility layer. If this is intentional cleanup, it should be noted explicitly._template.py: SimplifiedTemplateBuildandTemplateInfowith fewer fields. Breaking change for downstream consumers using fields likephase,progress,error_message.
2. Example deletion (CubeAPI/examples/snapshot-rollback-clone/)
11 Python example files + README (EN/ZH) + env.py + requirements.txt were deleted. Was this because the snapshot/rollback APIs have changed and these examples are no longer accurate?
3. Test file deletions (sdk/python/tests/)
test_template_e2e.py (116 lines) was deleted and conftest.py was modified. Are there replacement tests elsewhere?
4. Documentation link cleanup (docs/)
Multiple .md → clean URL conversions in internal links (e.g., ./quickstart.md → ./quickstart). Looks like a correctness fix — just note this in the PR description.
5. Snapshot guide deletion (docs/guide/snapshot-rollback-clone.md)
The entire snapshot/rollback/clone guide (150 lines, in both EN and ZH) was deleted. This is user-facing documentation removal and should be called out in the PR description with a reason.
Summary
The openapi.yml restructuring is solid, but the PR scope is significantly broader than the title "update openapi.yml". Please consider:
- Updating the PR description to document all the SDK model changes, example deletions, and documentation changes
- Clarifying the SDK version reversal (
0.2.0→0.1.0) — confirm this is intentional - Adding missing error responses to
/config,/store/*, and/templates/{id}/builds/{bid}/logsif those endpoints can actually fail - Adding a changelog or migration note for the SDK breaking changes if downstream consumers exist
Review in progress — full analysis complete.
Synchronize the OpenAPI spec with the actual CubeAPI endpoints, request/response schemas, and error codes. Signed-off-by: HouJinxin <houjinxin@example.com>
woshihoujinxin
force-pushed
the
docs/update-openapi
branch
from
327d2d0 to
ccc886b
Compare
|
Claude finished @woshihoujinxin's task in 2m 34s —— View job PR Review: docs: update openapi.yml to match CubeAPI implementationI've performed a detailed comparison of the updated ✅ Endpoint Coverage — All VerifiedAll 31 routes documented in
✅ Schema VerificationKey schemas checked against Rust models (
|
…tore endpoints Closes review comments on PR TencentCloud#381: - POST /templates/{id}/builds/{id}: add 400, 404, 500 - GET /templates/{id}/builds/{id}/status: add 404, 500 - GET /templates/{id}/builds/{id}/logs: add 404, 500 - GET /config: add 500 - GET /store/meta: add 500 - POST /store/refresh: add 500
…tore endpoints Closes review comments on PR TencentCloud#381: - POST /templates/{id}/builds/{id}: add 400, 404, 500 - GET /templates/{id}/builds/{id}/status: add 404, 500 - GET /templates/{id}/builds/{id}/logs: add 404, 500 - GET /config: add 500 - GET /store/meta: add 500 - POST /store/refresh: add 500
…tore endpoints Closes review comments on PR TencentCloud#381: - POST /templates/{id}/builds/{id}: add 400, 404, 500 - GET /templates/{id}/builds/{id}/status: add 404, 500 - GET /templates/{id}/builds/{id}/logs: add 404, 500 - GET /config: add 500 - GET /store/meta: add 500 - POST /store/refresh: add 500
1 participant
Problem
The
openapi.ymlspec was outdated and did not reflect the actual CubeAPI endpoints, request/response schemas, and error codes.Changes