Skip to content

Commit 33f7795

Browse files
beran-tberan-t
committed
Add short summaries to all platform endpoints for readable Mintlify sidebar names
1 parent 0538910 commit 33f7795

2 files changed

Lines changed: 84 additions & 0 deletions

File tree

‎openapi-public.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ paths:
4141
'500':
4242
$ref: '#/components/responses/500'
4343
operationId: listSandboxes
44+
summary: List sandboxes
4445
post:
4546
description: Create a sandbox from the template
4647
tags:
@@ -67,6 +68,7 @@ paths:
6768
'500':
6869
$ref: '#/components/responses/500'
6970
operationId: postSandboxes
71+
summary: Create sandbox
7072
servers:
7173
- *id001
7274
/v2/sandboxes:
@@ -113,6 +115,7 @@ paths:
113115
'500':
114116
$ref: '#/components/responses/500'
115117
operationId: listSandboxesV2
118+
summary: List sandboxes (v2)
116119
servers:
117120
- *id001
118121
/sandboxes/metrics:
@@ -148,6 +151,7 @@ paths:
148151
'500':
149152
$ref: '#/components/responses/500'
150153
operationId: listSandboxesMetrics
154+
summary: List sandbox metrics
151155
servers:
152156
- *id001
153157
/sandboxes/{sandboxID}/logs:
@@ -189,6 +193,7 @@ paths:
189193
'500':
190194
$ref: '#/components/responses/500'
191195
operationId: getSandboxLogs
196+
summary: Get sandbox logs
192197
servers:
193198
- *id001
194199
/sandboxes/{sandboxID}:
@@ -214,6 +219,7 @@ paths:
214219
'500':
215220
$ref: '#/components/responses/500'
216221
operationId: getSandbox
222+
summary: Get sandbox
217223
delete:
218224
description: Kill a sandbox
219225
tags:
@@ -232,6 +238,7 @@ paths:
232238
'500':
233239
$ref: '#/components/responses/500'
234240
operationId: deleteSandbox
241+
summary: Delete sandbox
235242
servers:
236243
- *id001
237244
/sandboxes/{sandboxID}/metrics:
@@ -277,6 +284,7 @@ paths:
277284
'500':
278285
$ref: '#/components/responses/500'
279286
operationId: getSandboxMetrics
287+
summary: Get sandbox metrics
280288
servers:
281289
- *id001
282290
/sandboxes/{sandboxID}/pause:
@@ -300,6 +308,7 @@ paths:
300308
'500':
301309
$ref: '#/components/responses/500'
302310
operationId: postSandboxPause
311+
summary: Pause sandbox
303312
servers:
304313
- *id001
305314
/sandboxes/{sandboxID}/resume:
@@ -334,6 +343,7 @@ paths:
334343
'500':
335344
$ref: '#/components/responses/500'
336345
operationId: postSandboxResume
346+
summary: Resume sandbox
337347
servers:
338348
- *id001
339349
/sandboxes/{sandboxID}/connect:
@@ -374,6 +384,7 @@ paths:
374384
'500':
375385
$ref: '#/components/responses/500'
376386
operationId: postSandboxConnect
387+
summary: Connect to sandbox
377388
servers:
378389
- *id001
379390
/sandboxes/{sandboxID}/timeout:
@@ -412,6 +423,7 @@ paths:
412423
'500':
413424
$ref: '#/components/responses/500'
414425
operationId: postSandboxTimeout
426+
summary: Set sandbox timeout
415427
servers:
416428
- *id001
417429
/sandboxes/{sandboxID}/refreshes:
@@ -445,6 +457,7 @@ paths:
445457
'500':
446458
$ref: '#/components/responses/500'
447459
operationId: postSandboxRefreshes
460+
summary: Refresh sandbox
448461
servers:
449462
- *id001
450463
/v3/templates:
@@ -474,6 +487,7 @@ paths:
474487
'500':
475488
$ref: '#/components/responses/500'
476489
operationId: postTemplatesV3
490+
summary: Create template (v3)
477491
servers:
478492
- *id001
479493
/v2/templates:
@@ -504,6 +518,7 @@ paths:
504518
'500':
505519
$ref: '#/components/responses/500'
506520
operationId: postTemplatesV2
521+
summary: Create template (v2)
507522
servers:
508523
- *id001
509524
/templates/{templateID}/files/{hash}:
@@ -538,6 +553,7 @@ paths:
538553
schema:
539554
$ref: '#/components/schemas/TemplateBuildFileUpload'
540555
operationId: getTemplateFile
556+
summary: Get build upload link
541557
servers:
542558
- *id001
543559
/templates:
@@ -570,6 +586,7 @@ paths:
570586
'500':
571587
$ref: '#/components/responses/500'
572588
operationId: listTemplates
589+
summary: List templates
573590
post:
574591
description: Create a new template
575592
deprecated: true
@@ -597,6 +614,7 @@ paths:
597614
'500':
598615
$ref: '#/components/responses/500'
599616
operationId: postTemplates
617+
summary: Create template
600618
servers:
601619
- *id001
602620
/templates/{templateID}:
@@ -622,6 +640,7 @@ paths:
622640
'500':
623641
$ref: '#/components/responses/500'
624642
operationId: getTemplate
643+
summary: Get template
625644
post:
626645
description: Rebuild an template
627646
deprecated: true
@@ -649,6 +668,7 @@ paths:
649668
'500':
650669
$ref: '#/components/responses/500'
651670
operationId: postTemplate
671+
summary: Rebuild template
652672
delete:
653673
description: Delete a template
654674
tags:
@@ -666,6 +686,7 @@ paths:
666686
'500':
667687
$ref: '#/components/responses/500'
668688
operationId: deleteTemplate
689+
summary: Delete template
669690
patch:
670691
description: Update template
671692
deprecated: true
@@ -696,6 +717,7 @@ paths:
696717
'500':
697718
$ref: '#/components/responses/500'
698719
operationId: patchTemplate
720+
summary: Update template
699721
servers:
700722
- *id001
701723
/templates/{templateID}/builds/{buildID}:
@@ -722,6 +744,7 @@ paths:
722744
'500':
723745
$ref: '#/components/responses/500'
724746
operationId: postTemplateBuild
747+
summary: Start build
725748
servers:
726749
- *id001
727750
/v2/templates/{templateID}/builds/{buildID}:
@@ -749,6 +772,7 @@ paths:
749772
'500':
750773
$ref: '#/components/responses/500'
751774
operationId: postTemplateBuildV2
775+
summary: Start build (v2)
752776
servers:
753777
- *id001
754778
/v2/templates/{templateID}:
@@ -781,6 +805,7 @@ paths:
781805
'500':
782806
$ref: '#/components/responses/500'
783807
operationId: patchTemplateV2
808+
summary: Update template (v2)
784809
servers:
785810
- *id001
786811
/templates/{templateID}/builds/{buildID}/status:
@@ -830,6 +855,7 @@ paths:
830855
'500':
831856
$ref: '#/components/responses/500'
832857
operationId: getTemplateBuildStatus
858+
summary: Get build status
833859
servers:
834860
- *id001
835861
/templates/{templateID}/builds/{buildID}/logs:
@@ -886,6 +912,7 @@ paths:
886912
'500':
887913
$ref: '#/components/responses/500'
888914
operationId: getTemplateBuildLogs
915+
summary: Get build logs
889916
servers:
890917
- *id001
891918
/templates/aliases/{alias}:
@@ -918,6 +945,7 @@ paths:
918945
'500':
919946
$ref: '#/components/responses/500'
920947
operationId: getTemplatesAlias
948+
summary: Get template by alias
921949
servers:
922950
- *id001
923951
/filesystem.Filesystem/CreateWatcher:
@@ -1548,6 +1576,7 @@ paths:
15481576
'500':
15491577
$ref: '#/components/responses/500'
15501578
operationId: postTemplatesTags
1579+
summary: Assign tags
15511580
delete:
15521581
description: Delete multiple tags from templates
15531582
tags:
@@ -1572,6 +1601,7 @@ paths:
15721601
'500':
15731602
$ref: '#/components/responses/500'
15741603
operationId: deleteTemplatesTags
1604+
summary: Delete tags
15751605
servers:
15761606
- *id001
15771607
/templates/{templateID}/tags:
@@ -1601,6 +1631,7 @@ paths:
16011631
'500':
16021632
$ref: '#/components/responses/500'
16031633
operationId: getTemplateTags
1634+
summary: List template tags
16041635
servers:
16051636
- *id001
16061637
/teams:
@@ -1625,6 +1656,7 @@ paths:
16251656
'500':
16261657
$ref: '#/components/responses/500'
16271658
operationId: listTeams
1659+
summary: List teams
16281660
servers:
16291661
- *id001
16301662
/teams/{teamID}/metrics:
@@ -1670,6 +1702,7 @@ paths:
16701702
'500':
16711703
$ref: '#/components/responses/500'
16721704
operationId: getTeamMetrics
1705+
summary: Get team metrics
16731706
servers:
16741707
- *id001
16751708
/teams/{teamID}/metrics/max:
@@ -1722,6 +1755,7 @@ paths:
17221755
'500':
17231756
$ref: '#/components/responses/500'
17241757
operationId: getTeamMetricsMax
1758+
summary: Get team metrics max
17251759
servers:
17261760
- *id001
17271761
/health:

‎scripts/generate_openapi_reference.py‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1062,6 +1062,56 @@ def _singularize(word: str) -> str:
10621062
json_media["example"] = example
10631063
fixes.append("Error responses: added per-status example values")
10641064

1065+
# 26. Add short summary fields to platform endpoints for Mintlify sidebar names
1066+
SUMMARIES: dict[tuple[str, str], str] = {
1067+
# Sandboxes
1068+
("/sandboxes", "get"): "List sandboxes",
1069+
("/sandboxes", "post"): "Create sandbox",
1070+
("/v2/sandboxes", "get"): "List sandboxes (v2)",
1071+
("/sandboxes/metrics", "get"): "List sandbox metrics",
1072+
("/sandboxes/{sandboxID}/logs", "get"): "Get sandbox logs",
1073+
("/sandboxes/{sandboxID}", "get"): "Get sandbox",
1074+
("/sandboxes/{sandboxID}", "delete"): "Delete sandbox",
1075+
("/sandboxes/{sandboxID}/metrics", "get"): "Get sandbox metrics",
1076+
("/sandboxes/{sandboxID}/pause", "post"): "Pause sandbox",
1077+
("/sandboxes/{sandboxID}/resume", "post"): "Resume sandbox",
1078+
("/sandboxes/{sandboxID}/connect", "post"): "Connect to sandbox",
1079+
("/sandboxes/{sandboxID}/timeout", "post"): "Set sandbox timeout",
1080+
("/sandboxes/{sandboxID}/refreshes", "post"): "Refresh sandbox",
1081+
# Templates
1082+
("/v3/templates", "post"): "Create template (v3)",
1083+
("/v2/templates", "post"): "Create template (v2)",
1084+
("/templates/{templateID}/files/{hash}", "get"): "Get build upload link",
1085+
("/templates", "get"): "List templates",
1086+
("/templates", "post"): "Create template",
1087+
("/templates/{templateID}", "get"): "Get template",
1088+
("/templates/{templateID}", "post"): "Rebuild template",
1089+
("/templates/{templateID}", "delete"): "Delete template",
1090+
("/templates/{templateID}", "patch"): "Update template",
1091+
("/templates/{templateID}/builds/{buildID}", "post"): "Start build",
1092+
("/v2/templates/{templateID}/builds/{buildID}", "post"): "Start build (v2)",
1093+
("/v2/templates/{templateID}", "patch"): "Update template (v2)",
1094+
("/templates/{templateID}/builds/{buildID}/status", "get"): "Get build status",
1095+
("/templates/{templateID}/builds/{buildID}/logs", "get"): "Get build logs",
1096+
("/templates/aliases/{alias}", "get"): "Get template by alias",
1097+
# Tags
1098+
("/templates/tags", "post"): "Assign tags",
1099+
("/templates/tags", "delete"): "Delete tags",
1100+
("/templates/{templateID}/tags", "get"): "List template tags",
1101+
# Teams
1102+
("/teams", "get"): "List teams",
1103+
("/teams/{teamID}/metrics", "get"): "Get team metrics",
1104+
("/teams/{teamID}/metrics/max", "get"): "Get team metrics max",
1105+
}
1106+
summary_count = 0
1107+
for (path_str, method), summary in SUMMARIES.items():
1108+
op = paths.get(path_str, {}).get(method)
1109+
if op:
1110+
op["summary"] = summary
1111+
summary_count += 1
1112+
if summary_count:
1113+
fixes.append(f"Added summary to {summary_count} platform endpoints")
1114+
10651115
if fixes:
10661116
print(f"==> Fixed {len(fixes)} spec issues:")
10671117
for f in fixes:

0 commit comments

Comments
 (0)