Skip to content

Commit c0a60da

Browse files
beran-tjakubno
beran-t
and
jakubno
authored
Add API Reference to docs navigation (#127)
* Add API Reference section to docs navigation Add OpenAPI-based API Reference anchor to docs.json alongside the existing SDK Reference, pointing to openapi-public.yml spec. * Add OpenAPI generation and validation scripts - scripts/envd.py: Merges proto-generated and hand-written specs into a single openapi-public.yml - scripts/validate_api_reference.py: Validates the spec against the live API across 12 phases * Rename envd.py to generate_openapi_reference.py * Refactor generate script to fetch specs from e2b-dev/infra The script now clones e2b-dev/infra at specified commits inside Docker instead of reading from local paths. Supports separate --envd-commit and --api-commit flags (defaults to main). Regenerated openapi-public.yml from latest main. * Require sandbox access token auth on all envd endpoints Sandbox endpoints always require Authorization: Bearer <token> using the envdAccessToken from sandbox creation. Update generate script to set required auth, update validate script to always pass token and create sandboxes with secure: true. * Fix auth schemes: restore AccessTokenAuth (Bearer), add E2B_ACCESS_TOKEN support - Keep AccessTokenAuth (type: http, scheme: bearer) for platform endpoints - Remove /files from AUTH_EXEMPT_ENDPOINTS (only /health is exempt) - Add E2B_ACCESS_TOKEN env var to validate script for Bearer auth testing - Pass sandbox access token to /files endpoints in validate script - Fix sandboxID server variable default to $SANDBOX_ID * Add E2B_ACCESS_TOKEN support and improve team ID discovery - Add bearer_hdr() helper for AccessTokenAuth endpoints - Read E2B_ACCESS_TOKEN env var for GET /teams and legacy template endpoints - Discover team ID via GET /teams when Bearer token is available * Fix spec validation findings: 20 critical → 0 Generate script (fix_spec_issues): - Add 'uploaded' to TemplateBuildStatus enum - Make 'volumeMounts' optional in SandboxDetail/ListedSandbox - Remove strict LogLevel enum (server sends non-enum values) - Add mem_used_mib/mem_total_mib to Metrics schema Validate script: - Fix /health expected status to 204 - Fix /init expected status to 401 (re-init rejected) - Remove /v2/sandboxes/{id}/logs test (endpoint doesn't exist) * Strip content blocks from 204 responses 204 means No Content — don't add application/json schema to these responses. * Prefix auth description links with /docs * Add success-path tests for all template write endpoints - POST /v3/templates (202): create template, validate schema, clean up - POST /v2/templates (202): create template, validate schema, clean up - PATCH /v2/templates/{templateID} (200): update public field, validate schema - PATCH /templates/{templateID} (200): deprecated endpoint success test - POST /v2/.../builds/{buildID} (202): start build on created template - POST /templates/tags (201): assign tag using existing name:tag target - DELETE /templates/tags (204): remove test tag - DELETE /templates/{templateID}: real cleanup of test templates - GET /templates/{templateID}/tags: discover existing tags in phase 2 - Drop minor findings from report and exit code (CI-oriented) * Fix 8 spec issues found during SDK testing 1. Streaming RPCs: content-type → application/connect+json, add Connect-Protocol-Version and Connect-Timeout-Ms headers 2. EndEvent.exitCode: marked deprecated, document status string parsing 3. envdAccessToken: clarify only returned with secure: true, mark nullable 4. LogLevel: fix description ("State of the sandbox" → log severity) 5. Sandbox.domain: mark deprecated (always null) 6. GET /templates/{id}/files/{hash}: change 201 → 200 response Issues 4 (pagination response) and 5 (DELETE with body) are upstream API design decisions that cannot be fixed in the spec alone. * Fix 12 spec inconsistencies from SDK testing report Generation script fixes (fix_spec_issues): - Generate operationId for all 52 platform endpoints - Remove phantom /v2/sandboxes/{sandboxID}/logs deprecation reference - Complete truncated 'start'/'end' parameter descriptions on metrics - Fix sandboxId → sandboxID casing in 502 error schema - Add security: [] and 'health' tag to GET /health - Remove YAML anchor overlay on /files responses (DownloadSuccess/UploadSuccess) - Add type: object to 53 schemas missing it - Move 'end' param description out of schema to sibling level Also fix fill_empty_responses to skip $ref responses. Upstream issues not fixable in spec: - allow_internet_access snake_case (server field name) - Duplicate EntryInfo schemas (different APIs) - Inconsistent error response coverage (API behavior) - Auth inconsistency across template versions (intentional v1→v2/v3) * Fix schema and consistency issues from second SDK testing round Schema fixes: - EntryInfo.type: add 'directory' to enum (was file-only) - SandboxMetadata, EnvVars: add type: object (had only additionalProperties) - TemplateLegacy: add missing 'names' and 'buildStatus' fields - connect-protocol-version: remove redundant enum (const suffices) - filesystem.EntryInfo.size: document int/string union type (int64) Response fixes: - PATCH /templates/{templateID}: return TemplateUpdateResponse (was empty) - POST /sandboxes/{sandboxID}/refreshes: add missing 500 response - GET /health 502: content-type → application/json (was connect+json) Also fix fill_empty_responses to skip $ref responses. * Fix duplicate and misspelled operationIds - Rewrite operationId generator with proper singularization (sandboxes→sandbox, not sandboxe) - Use 'list' prefix for collection GETs (listSandboxes, listTemplates) - Include version suffix for v2/v3 variants (postTemplatesV3) - Singularize parent resource when followed by path param (GET /sandboxes/{id}/logs → getSandboxLogs) - Dedup check ensures all 52 platform operationIds are unique * Exclude snapshots/volumes endpoints, merge auth tests into Teams phase * Rename and reorder API reference tags for documentation sidebar * Reorder paths by tag to match desired Mintlify sidebar order * Tag untagged endpoints (/metrics, /envs) as Others so they appear in the correct section * Add meaningful examples to error responses (400/401/403/404/409/500) * Inline /files response definitions so Mintlify renders them correctly * Move error example to Error schema so it applies to all references * Add per-status error examples so each error response shows correct code and message * Lowercase 'reference' in SDK reference and API reference anchors * Add short summaries to all platform endpoints for readable Mintlify sidebar names * Set format: int64 on Metrics memory/disk fields to prevent overflow * Replace nullable: true with OpenAPI 3.1.0 type arrays on 14 properties * Fix validation script: correct expected statuses, remove internal endpoints, add status mismatch catch-all - Change DELETE /templates/{templateID} cleanup expected status from 200 to 204 - Remove POST /init test (internal endpoint, not in public spec) - Remove unauthenticated 401 tests to avoid load balancer rate limiting - Use account-owned template alias instead of hardcoded 'base' for alias test - Send no-op Update to process instead of PTY resize (avoids 500 on non-PTY process) - Add post-processing catch-all that flags any tested endpoint with unexpected status code * Hide deprecated badges in sidebar to prevent endpoint name truncation * Add API reference validation workflow (manual trigger only for now) * Fix validation script: remove Bearer-only tests, move alias test to phase 3, update workflow - Remove 3 endpoints that tested API key against Bearer-only endpoints (just confirmed 401) - Move GET /templates/aliases/{alias} test to phase 3, use the test template we create there - Update workflow to generate spec, diff, run validation, and create PR with status indicator * Remove openapi-validation-report.md from repo * Hide scrollbar on sidebar API endpoint rows with deprecated badges * edit workflow * test true * works, back to false * Make workflow run on schedule (disabled for now) * Add snapshots endpoints and update auto-resume config in API reference - Add POST /sandboxes/{sandboxID}/snapshots and GET /snapshots endpoints - Add SnapshotInfo schema and FILE_TYPE_SYMLINK enum value - Replace SandboxAutoResumePolicy enum with SandboxAutoResumeEnabled boolean - Stop filtering out snapshot paths in generate script * Map snapshots tag to Sandboxes section in generate script * Remove validation script and simplify workflow to generate-and-PR only * Remove example fields from generate script and regenerate spec * Update docs.json * Reorder API reference sidebar: move Tags under Templates, rename Others to Envd, move /files to Filesystem, move Teams to end --------- Co-authored-by: Jakub Novák <kubus.novak@gmail.com>
1 parent 2f7a1d8 commit c0a60da

File tree

5 files changed

+5864
-0
lines changed

5 files changed

+5864
-0
lines changed

‎.github/workflows/api-reference-validation.yml‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
name: API Reference Validation
2+
3+
on:
4+
# schedule:
5+
# # Every Thursday at 8 PM UTC
6+
# - cron: '0 20 * * 4'
7+
workflow_dispatch:
8+
9+
concurrency:
10+
group: api-reference-validation
11+
cancel-in-progress: false
12+
13+
jobs:
14+
validate:
15+
runs-on: ubuntu-latest
16+
timeout-minutes: 20
17+
permissions:
18+
contents: write
19+
pull-requests: write
20+
21+
steps:
22+
- name: Checkout
23+
uses: actions/checkout@v4
24+
25+
- name: Setup Python
26+
uses: actions/setup-python@v5
27+
with:
28+
python-version: '3.11'
29+
30+
- name: Install dependencies
31+
run: pip install pyyaml
32+
33+
# Step 1: Generate spec from source
34+
- name: Generate OpenAPI spec
35+
run: python3 scripts/generate_openapi_reference.py --output openapi-generated.yml
36+
37+
# Step 2: Compare with committed spec
38+
- name: Compare specs
39+
id: diff
40+
run: |
41+
if diff -q openapi-public.yml openapi-generated.yml > /dev/null 2>&1; then
42+
echo "Spec is up to date — nothing to do"
43+
echo "changed=false" >> $GITHUB_OUTPUT
44+
else
45+
echo "Spec has drifted from source"
46+
echo "changed=true" >> $GITHUB_OUTPUT
47+
fi
48+
49+
# Step 3: Create PR if spec has drifted
50+
- name: Create PR
51+
if: steps.diff.outputs.changed == 'true'
52+
env:
53+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
54+
run: |
55+
cp openapi-generated.yml openapi-public.yml
56+
57+
BRANCH="api-spec-update-$(date +%Y-%m-%d)"
58+
git config user.name "github-actions[bot]"
59+
git config user.email "github-actions[bot]@users.noreply.github.com"
60+
61+
git checkout -b "$BRANCH"
62+
git add openapi-public.yml
63+
git commit -m "docs: update openapi-public.yml from source specs $(date +%Y-%m-%d)"
64+
git push -u origin "$BRANCH"
65+
66+
gh pr create \
67+
--title "Update API spec $(date +%Y-%m-%d)" \
68+
--body "$(cat <<EOF
69+
## OpenAPI Spec Update
70+
71+
The generated \`openapi-public.yml\` has drifted from the source specs.
72+
This PR updates it to match the latest upstream definitions.
73+
EOF
74+
)" \
75+
--base main
76+
77+
- name: Summary
78+
if: always()
79+
env:
80+
CHANGED: ${{ steps.diff.outputs.changed }}
81+
run: |
82+
echo "## API Reference Spec Check" >> $GITHUB_STEP_SUMMARY
83+
echo "" >> $GITHUB_STEP_SUMMARY
84+
echo "| Result | Value |" >> $GITHUB_STEP_SUMMARY
85+
echo "|--------|-------|" >> $GITHUB_STEP_SUMMARY
86+
echo "| Spec changed | ${CHANGED:-false} |" >> $GITHUB_STEP_SUMMARY

‎docs.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3620,6 +3620,14 @@
36203620
]
36213621
}
36223622
]
3623+
},
3624+
{
3625+
"anchor": "API reference",
3626+
"icon": "code",
3627+
"openapi": {
3628+
"source": "openapi-public.yml",
3629+
"directory": "docs/api-reference"
3630+
}
36233631
}
36243632
],
36253633
"global": {}

0 commit comments

Comments
 (0)