Expand OpenAPI response schemas in reference docs

reference-config/operations.yaml

@@ -10,45 +10,45 @@ controlPlane:
     - templates
     - tags
   operations:
-    GET /teams/{teamID}/metrics: { id: getTeamMetrics, group: team-metrics, slug: team-metrics }
-    GET /teams/{teamID}/metrics/max: { id: getTeamMetricsMax, group: team-metrics, slug: team-metrics-max }
-    POST /sandboxes: { id: createSandbox, group: sandboxes, slug: create }
-    GET /v2/sandboxes: { id: listSandboxes, group: sandboxes, slug: list }
-    GET /sandboxes/metrics: { id: listSandboxMetrics, group: sandboxes, slug: list-metrics }
-    GET /v2/sandboxes/{sandboxID}/logs: { id: getSandboxLogs, group: sandboxes, slug: logs }
-    GET /sandboxes/{sandboxID}: { id: getSandbox, group: sandboxes, slug: get }
-    DELETE /sandboxes/{sandboxID}: { id: killSandbox, group: sandboxes, slug: kill }
-    GET /sandboxes/{sandboxID}/metrics: { id: getSandboxMetrics, group: sandboxes, slug: metrics }
-    POST /sandboxes/{sandboxID}/pause: { id: pauseSandbox, group: sandboxes, slug: pause }
-    POST /sandboxes/{sandboxID}/fork: { id: forkSandbox, group: sandboxes, slug: fork }
-    POST /sandboxes/{sandboxID}/connect: { id: connectSandbox, group: sandboxes, slug: connect }
-    POST /sandboxes/{sandboxID}/timeout: { id: setSandboxTimeout, group: sandboxes, slug: timeout }
-    PUT /sandboxes/{sandboxID}/network: { id: updateSandboxNetwork, group: sandboxes, slug: network }
-    POST /sandboxes/{sandboxID}/refreshes: { id: refreshSandbox, group: sandboxes, slug: refresh }
-    POST /sandboxes/{sandboxID}/snapshots: { id: createSnapshot, group: snapshots, slug: create }
-    GET /snapshots: { id: listSnapshots, group: snapshots, slug: list }
-    POST /v3/templates: { id: createTemplate, group: templates, slug: create }
-    GET /v2/templates: { id: listTemplates, group: templates, slug: list }
-    GET /templates/{templateID}/files/{hash}: { id: getTemplateUploadUrl, group: templates, slug: upload-url }
-    GET /templates/{templateID}: { id: getTemplate, group: templates, slug: get }
-    DELETE /templates/{templateID}: { id: deleteTemplate, group: templates, slug: delete }
-    POST /v2/templates/{templateID}/builds/{buildID}: { id: startTemplateBuild, group: templates, slug: start-build }
-    PATCH /v2/templates/{templateID}: { id: updateTemplate, group: templates, slug: update }
-    GET /templates/{templateID}/builds/{buildID}/status: { id: getTemplateBuildStatus, group: templates, slug: build-status }
-    GET /templates/{templateID}/builds/{buildID}/logs: { id: getTemplateBuildLogs, group: templates, slug: build-logs }
-    POST /templates/tags: { id: assignTemplateTags, group: tags, slug: assign }
-    DELETE /templates/tags: { id: deleteTemplateTags, group: tags, slug: delete }
-    GET /templates/{templateID}/tags: { id: listTemplateTags, group: tags, slug: list }
-    GET /templates/aliases/{alias}: { id: getTemplateByAlias, group: templates, slug: alias }
+    GET /teams/{teamID}/metrics: { id: getTeamMetrics, group: team-metrics, slug: team-metrics, summary: Get team metrics }
+    GET /teams/{teamID}/metrics/max: { id: getTeamMetricsMax, group: team-metrics, slug: team-metrics-max, summary: Get maximum team metrics }
+    POST /sandboxes: { id: createSandbox, group: sandboxes, slug: create, summary: Create sandbox }
+    GET /v2/sandboxes: { id: listSandboxes, group: sandboxes, slug: list, summary: List sandboxes }
+    GET /sandboxes/metrics: { id: listSandboxMetrics, group: sandboxes, slug: list-metrics, summary: List sandbox metrics }
+    GET /v2/sandboxes/{sandboxID}/logs: { id: getSandboxLogs, group: sandboxes, slug: logs, summary: Get sandbox logs }
+    GET /sandboxes/{sandboxID}: { id: getSandbox, group: sandboxes, slug: get, summary: Get sandbox }
+    DELETE /sandboxes/{sandboxID}: { id: killSandbox, group: sandboxes, slug: kill, summary: Kill sandbox }
+    GET /sandboxes/{sandboxID}/metrics: { id: getSandboxMetrics, group: sandboxes, slug: metrics, summary: Get sandbox metrics }
+    POST /sandboxes/{sandboxID}/pause: { id: pauseSandbox, group: sandboxes, slug: pause, summary: Pause sandbox }
+    POST /sandboxes/{sandboxID}/fork: { id: forkSandbox, group: sandboxes, slug: fork, summary: Fork sandbox }
+    POST /sandboxes/{sandboxID}/connect: { id: connectSandbox, group: sandboxes, slug: connect, summary: Connect sandbox }
+    POST /sandboxes/{sandboxID}/timeout: { id: setSandboxTimeout, group: sandboxes, slug: timeout, summary: Set sandbox timeout }
+    PUT /sandboxes/{sandboxID}/network: { id: updateSandboxNetwork, group: sandboxes, slug: network, summary: Update sandbox network }
+    POST /sandboxes/{sandboxID}/refreshes: { id: refreshSandbox, group: sandboxes, slug: refresh, summary: Refresh sandbox }
+    POST /sandboxes/{sandboxID}/snapshots: { id: createSnapshot, group: snapshots, slug: create, summary: Create snapshot }
+    GET /snapshots: { id: listSnapshots, group: snapshots, slug: list, summary: List snapshots }
+    POST /v3/templates: { id: createTemplate, group: templates, slug: create, summary: Create template }
+    GET /v2/templates: { id: listTemplates, group: templates, slug: list, summary: List templates }
+    GET /templates/{templateID}/files/{hash}: { id: getTemplateUploadUrl, group: templates, slug: upload-url, summary: Get template upload URL }
+    GET /templates/{templateID}: { id: getTemplate, group: templates, slug: get, summary: Get template }
+    DELETE /templates/{templateID}: { id: deleteTemplate, group: templates, slug: delete, summary: Delete template }
+    POST /v2/templates/{templateID}/builds/{buildID}: { id: startTemplateBuild, group: templates, slug: start-build, summary: Start template build }
+    PATCH /v2/templates/{templateID}: { id: updateTemplate, group: templates, slug: update, summary: Update template }
+    GET /templates/{templateID}/builds/{buildID}/status: { id: getTemplateBuildStatus, group: templates, slug: build-status, summary: Get template build status }
+    GET /templates/{templateID}/builds/{buildID}/logs: { id: getTemplateBuildLogs, group: templates, slug: build-logs, summary: Get template build logs }
+    POST /templates/tags: { id: assignTemplateTags, group: tags, slug: assign, summary: Assign template tags }
+    DELETE /templates/tags: { id: deleteTemplateTags, group: tags, slug: delete, summary: Delete template tags }
+    GET /templates/{templateID}/tags: { id: listTemplateTags, group: tags, slug: list, summary: List template tags }
+    GET /templates/aliases/{alias}: { id: getTemplateByAlias, group: templates, slug: alias, summary: Get template by alias }
 
 envd:
   source: spec/envd/envd.yaml
   publicAuthSchemes:
     - AccessTokenAuth
   operations:
-    GET /health: { id: getEnvironmentHealth, group: environment, slug: health }
-    GET /metrics: { id: getEnvironmentMetrics, group: environment, slug: metrics }
-    GET /envs: { id: getEnvironmentVariables, group: environment, slug: variables }
-    GET /files: { id: downloadFile, group: files, slug: download }
-    POST /files: { id: uploadFile, group: files, slug: upload }
-    POST /files/compose: { id: composeFiles, group: files, slug: compose }
+    GET /health: { id: getEnvironmentHealth, group: environment, slug: health, summary: Check environment health }
+    GET /metrics: { id: getEnvironmentMetrics, group: environment, slug: metrics, summary: Get environment metrics }
+    GET /envs: { id: getEnvironmentVariables, group: environment, slug: variables, summary: Get environment variables }
+    GET /files: { id: downloadFile, group: files, slug: download, summary: Download file }
+    POST /files: { id: uploadFile, group: files, slug: upload, summary: Upload file }
+    POST /files/compose: { id: composeFiles, group: files, slug: compose, summary: Compose files }

reference/manifest.json

@@ -4,43 +4,43 @@
     "connect/process.md": "037574455e9e8c5159c391d8c007e7272560f62c4e5ee681f8aec29f9cd24539",
     "openapi/control-plane.yml": "95df3951c30223827e4933f1dab8c6e2c75a2a8d81269646f807427d11078548",
     "openapi/envd.yml": "30a0fba3b410c77db6b50b674f0ef9d110bf626ca2558820b5a6a05e4640cf19",
-    "openapi/markdown/assignTemplateTags.md": "fa9f7b2fd59332151695fab853f7f29b253e8837bbd6d8fa669258a303622819",
-    "openapi/markdown/composeFiles.md": "c814b69b4721e1a8c1a4d202bfc38feccfd12576071a21af8d9380baf6c2ff28",
-    "openapi/markdown/connectSandbox.md": "035437cfff8d3174ac6517b90c3da75dc338181ec19d07274cef46430453c6ed",
-    "openapi/markdown/createSandbox.md": "d9934ce3b88e1aa9df092fbff4ad88b87136b6ed786c3c7ca1aba86b361ac51a",
-    "openapi/markdown/createSnapshot.md": "b1aaf62afe3723c04fcd7c1f1b092a24a0342b28de2b680d6a9d0afc014ddc3b",
-    "openapi/markdown/createTemplate.md": "6e9fe66bc4a9671fd778620064989117fd40a560d5a0e2db874e6ade707384c4",
-    "openapi/markdown/deleteTemplate.md": "31f4140050bb8753a0e8294f4b60425695866b2a3930a861ed1657ec4fb07029",
-    "openapi/markdown/deleteTemplateTags.md": "94e5f1831a4044ea6acb248326fba83d9c6f0123bd61a3b2c401426fcd434b82",
-    "openapi/markdown/downloadFile.md": "3cded9f4d62b95e4fbb6bc4d548340c5943538010b04bfba690bfb042cd0ae4d",
-    "openapi/markdown/forkSandbox.md": "e773314d8f074b168db204072097c2bff06fac52960d5a89db5172a980ab8668",
+    "openapi/markdown/assignTemplateTags.md": "3ec3dc705cbda5780d0a9e78234c7777f014784b2ec193821b6f5bb2ea26ec57",
+    "openapi/markdown/composeFiles.md": "3e5c37b40268689b6e5287a906c75b80f71fefafe94205c6327c976ca0594d5c",
+    "openapi/markdown/connectSandbox.md": "9106d09a6f525aa0bcbd1eed06de62a4d015d1f6fa63496ccb6aebbebb3ad332",
+    "openapi/markdown/createSandbox.md": "42b8b28e9aac9bcbbacec9dec346d043340f8c94ac497147a80910341572226f",
+    "openapi/markdown/createSnapshot.md": "433724d1260fd60e68268a2984f7ca7ae54a1cad120fb25a026b6a6518af004f",
+    "openapi/markdown/createTemplate.md": "b31935eef9b0c29bcd9402f7401a4159c349bed8b3e5458c4490870574bc2974",
+    "openapi/markdown/deleteTemplate.md": "3f9a6ab1e0ab144f0a68e41938ef23fd07ac2509b16f6b4b9df5478e54a5865c",
+    "openapi/markdown/deleteTemplateTags.md": "1b907ed1b5d9cd55a3b21f46c207217af8a4efe0fe6ccb56a8f988567fc27395",
+    "openapi/markdown/downloadFile.md": "d687f0fadf42a0c8d40324fbf6a732677dae38ed1cf02a755cf86eb9a5155abc",
+    "openapi/markdown/forkSandbox.md": "bc7846648216b1104ed1d1661eb08b9881b3fef7616bfae49542eca1d228e76e",
     "openapi/markdown/getEnvironmentHealth.md": "640c9435ce216a6fd0e5da7ee646d8527e5de428c946fad219946f5c1de5622a",
-    "openapi/markdown/getEnvironmentMetrics.md": "32f7d61ddb8980caec0beaa3821b99e5f6ef90c0e812390d4d417844ec99acdc",
+    "openapi/markdown/getEnvironmentMetrics.md": "fb7ce3264e1500da24b21a07b5b180110fa573fc3fb476c146f4529c16e7c089",
     "openapi/markdown/getEnvironmentVariables.md": "12803bbc7e3f2638e16f013ce05b2a688d8085739e38049c1022452fd7881e50",
-    "openapi/markdown/getSandbox.md": "697dcedd7f51a776705eae4e0ea0c358f93da5d7408fae0e779a7eba39c88130",
-    "openapi/markdown/getSandboxLogs.md": "d5e3adfca5ff72d3b04ad8f2f5bb038ce429d8d7381cc37db33c9b4f393df047",
-    "openapi/markdown/getSandboxMetrics.md": "cc810ac8bd47c0bf3903a2a529d5489af61611cb7268ef2327f93007d08d9467",
-    "openapi/markdown/getTeamMetrics.md": "8cdaab8e8e3f089793e75ce6e831ee4effec72acf4f9297644503e175fc25368",
-    "openapi/markdown/getTeamMetricsMax.md": "ec55664edb022a0d60573c0500a4d47c78a34a3a2cd538b842438fb569c97cb8",
-    "openapi/markdown/getTemplate.md": "08d46844ebf9a8825375faa3ff447d4f79fd36d421e9ab576ca9aed266b861c6",
-    "openapi/markdown/getTemplateBuildLogs.md": "a9a58101cfbb8317a2cbfb0bf8ba35cfdb237cb318c1010309fc34e74da81052",
-    "openapi/markdown/getTemplateBuildStatus.md": "d27fafb869e7ec31271b71f54e82bd166f0548cafffbe3614d9b6bed9381f26b",
-    "openapi/markdown/getTemplateByAlias.md": "df84543b45bdff8db21e5084eb046b0cc46333d0a18dd296c04f9639a1ad6d71",
-    "openapi/markdown/getTemplateUploadUrl.md": "c93f0d82af88a13effcc1f99a327f65a404b30f94af44e9ce548c5bc2369163b",
-    "openapi/markdown/killSandbox.md": "bee51c4cbd21bcd055206ea7bd4adb348e9443e732ed58b6e6dd67b184838fcc",
-    "openapi/markdown/listSandboxMetrics.md": "91d7a84253345fc106b8aba88ee186d012530a631a23de088155705a51b9c8f9",
-    "openapi/markdown/listSandboxes.md": "dc9411c3f5014b70689a4391d2d6b005426cb629eda61c097a2491fbab1a0ee7",
-    "openapi/markdown/listSnapshots.md": "5aa146fc317fcf7ccb730041e9cf9eb86e0345bce0a5527041ce38b747a750da",
-    "openapi/markdown/listTemplateTags.md": "40639fca4f9bc1be9df4d062f41a85c75f171ed323455f848002fce6af1d4805",
-    "openapi/markdown/listTemplates.md": "981cf6aa70140ff88845f00abd741b1e4feacc11f0916015bc68e7e5e75fc434",
-    "openapi/markdown/pauseSandbox.md": "1dcad5a2c9deb444120e5ec2812e14d3a90b9ed1db557f5d5d0eb05035695acf",
-    "openapi/markdown/refreshSandbox.md": "445154db7266e2b111a98d164c6ce75432b7ffa01db66245deed487ce79605e6",
-    "openapi/markdown/setSandboxTimeout.md": "0a093a4a42241cd2945c966b94e78d1e04d62315a475acba3430655a6a201591",
-    "openapi/markdown/startTemplateBuild.md": "35d876994087cab1fbb8ae5251c66f952a9ce89425457afcc86ba4daefa256a5",
-    "openapi/markdown/updateSandboxNetwork.md": "30717801dfc58a1ddd3e7eb889af7ad2fec16ea7c6d8a13f8eb1356066165ac2",
-    "openapi/markdown/updateTemplate.md": "0e18de978fc7005ec36645d003827354df933fb9e51ba218fbdea55639c0636a",
-    "openapi/markdown/uploadFile.md": "acf5f7029d2b4de2ce96b50bb24f5e4495c188dfed878851ffe2f91e5b7b24d3",
-    "openapi/operations.json": "1593bd80b73d87117a5ebf8211d0ba014e0170c84fca5fe9f1a82ec457a6b575",
+    "openapi/markdown/getSandbox.md": "9e9f1200583b9abb206e7c69e9d4157403297042d2dd1e57e5bd804962073a91",
+    "openapi/markdown/getSandboxLogs.md": "6641f57b0ef9f7e029b66deb472616ea4abe54f3884b3021bfcf97b37920a598",
+    "openapi/markdown/getSandboxMetrics.md": "1572d44d0ff539495dadcbb909bb1e640b73375fcb4b0840243e692066162ace",
+    "openapi/markdown/getTeamMetrics.md": "063860650df86f09f1119f441b1410b1e329dd20000cf1b1f8a1f84fdcbdac53",
+    "openapi/markdown/getTeamMetricsMax.md": "5e5e6578470d1710c993ae69a91b34badaaa86e62e141eb91e57c6e0f7594fe6",
+    "openapi/markdown/getTemplate.md": "fa972635535ecb1b19324216185f75c90fe81520ed79dc7e20a0894306e054b3",
+    "openapi/markdown/getTemplateBuildLogs.md": "c1dc222e7ab5268897e8fdda893d1264ac9162db146fb89bbe6c9833f350ab7f",
+    "openapi/markdown/getTemplateBuildStatus.md": "26741b144d7ce26f353173bd0665b30925e6161d914317fb994bae5c2b4d0d3d",
+    "openapi/markdown/getTemplateByAlias.md": "2a42010266038d50581e3526becf1f35ad3ada6eecd757522b083817fe435301",
+    "openapi/markdown/getTemplateUploadUrl.md": "b06cb4aaed389e75daa8e509e3437a23915aad2b03ef6e69597df67984a48b19",
+    "openapi/markdown/killSandbox.md": "c864528a36849a512be77bf144ef7d41356f01cb0dbbe1d2f5143712a95268f2",
+    "openapi/markdown/listSandboxMetrics.md": "b945d76f80dc2fef506d2f21183bca49ddb045773b8895b6412e435e5c9d6d7f",
+    "openapi/markdown/listSandboxes.md": "7744505b60b94d1c8db8c1b7a1a66bcf9bdb8f51a46b13b5a90349e562924f59",
+    "openapi/markdown/listSnapshots.md": "d7f7ae67491c5da2930181b0fe423ef8ad661f5f4e7e88f47ecfb58cb08ac83f",
+    "openapi/markdown/listTemplateTags.md": "df27ed0dc04e6b49a3dc92704842e30365f50e88c8e28e6a5323a16aa10b7c45",
+    "openapi/markdown/listTemplates.md": "e89b7d18efcfa6e16385e6b4e2f227ad2e5c9fa7608426ece673077a35468e12",
+    "openapi/markdown/pauseSandbox.md": "0d1e7dd52ca966d37742e7d34898559dfd03c4ba3ca7f83f1859ddaefa9b0464",
+    "openapi/markdown/refreshSandbox.md": "dea1862241aad45c17b194994722a23941263bb697b885e795ba97cf154469bd",
+    "openapi/markdown/setSandboxTimeout.md": "ee0aaf78e2c0ffcdf4df1bde703fd4442d5436efad290bc235d1acc120adb997",
+    "openapi/markdown/startTemplateBuild.md": "befd11983028352bd7bf727113deb9bbb7d86d7b02385441111f4de46087173c",
+    "openapi/markdown/updateSandboxNetwork.md": "3449bd43a4e46c35d3f8ec314a47876ec06f85a8a75e4255212a85cb7a4c3e53",
+    "openapi/markdown/updateTemplate.md": "ace7930be4091213fc2e29a7109f489eaaf3a0e1d210aa65d9663a5adbf92250",
+    "openapi/markdown/uploadFile.md": "fe1dcc1b1eaad25ecd73f8c00a49c94ca7c2686fbdb6f3e2fbbebbfec6928806",
+    "openapi/operations.json": "f5097d93fb7eb5f6482e632624d5a212e29441ef8c558601ccbe2dae26db050d",
     "sdk/cli/auth.md": "0b2c75262b0c0670c7bc0f0f3cbed65fbe4a16d6fe4437789a5685b8bf2174a1",
     "sdk/cli/sandbox.md": "16b64c5a4e932eca2452e400e0faf154eba1d3c7373513aa7cd9744e02908313",
     "sdk/cli/template.md": "f270b22b9ee10a9b954a14f24e04c5449b4d5823bb28002ffde3ed682594cfc5",

reference/openapi/markdown/assignTemplateTags.md

@@ -12,10 +12,13 @@ Required: yes
 
 Schema: `AssignTemplateTagsRequest`
 
-| Field | Type | Required | Description |
-| --- | --- | --- | --- |
-| `target` | `string` | yes | Target template in "name:tag" format |
-| `tags` | `array<string>` | yes | Tags to assign to the template |
+- **`target`** · `string` · required
+
+  Target template in "name:tag" format
+
+- **`tags`** · `array<string>` · required
+
+  Tags to assign to the template
 
 ## Responses
 
@@ -27,10 +30,13 @@ Content-Type: `application/json`
 
 Schema: `AssignedTemplateTags`
 
-| Field | Type | Required | Description |
-| --- | --- | --- | --- |
-| `tags` | `array<string>` | yes | Assigned tags of the template |
-| `buildID` | `string` | yes | Identifier of the build associated with these tags |
+- **`tags`** · `array<string>` · required
+
+  Assigned tags of the template
+
+- **`buildID`** · `string` · required
+
+  Identifier of the build associated with these tags
 
 ### 400
 
@@ -40,10 +46,13 @@ Content-Type: `application/json`
 
 Schema: `Error`
 
-| Field | Type | Required | Description |
-| --- | --- | --- | --- |
-| `code` | `integer` | yes | Error code |
-| `message` | `string` | yes | Error |
+- **`code`** · `integer` · required
+
+  Error code
+
+- **`message`** · `string` · required
+
+  Error
 
 ### 401
 
@@ -53,10 +62,13 @@ Content-Type: `application/json`
 
 Schema: `Error`
 
-| Field | Type | Required | Description |
-| --- | --- | --- | --- |
-| `code` | `integer` | yes | Error code |
-| `message` | `string` | yes | Error |
+- **`code`** · `integer` · required
+
+  Error code
+
+- **`message`** · `string` · required
+
+  Error
 
 ### 404
 
@@ -66,10 +78,13 @@ Content-Type: `application/json`
 
 Schema: `Error`
 
-| Field | Type | Required | Description |
-| --- | --- | --- | --- |
-| `code` | `integer` | yes | Error code |
-| `message` | `string` | yes | Error |
+- **`code`** · `integer` · required
+
+  Error code
+
+- **`message`** · `string` · required
+
+  Error
 
 ### 500
 
@@ -79,7 +94,10 @@ Content-Type: `application/json`
 
 Schema: `Error`
 
-| Field | Type | Required | Description |
-| --- | --- | --- | --- |
-| `code` | `integer` | yes | Error code |
-| `message` | `string` | yes | Error |
+- **`code`** · `integer` · required
+
+  Error code
+
+- **`message`** · `string` · required
+
+  Error