Skip to content

Spike: How to document the public API? #153

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 25 commits into
base: main
Choose a base branch
from
Draft

Spike: How to document the public API? #153

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
6b6810d
feat(docs): reorganize reference section with runtime and rest api gr…
alexhwoods Sep 27, 2025
ecfcc18
feat(docs): integrate OpenAPI spec with Mintlify auto-generation
alexhwoods Sep 27, 2025
925faa8
feat(docs): add manual section control for REST API ordering
alexhwoods Sep 27, 2025
70a219a
feat(docs): remove UserAuth and FranchiseAuth security schemes
alexhwoods Sep 27, 2025
aa682e0
feat(docs): improve endpoint display names with summaries
alexhwoods Sep 27, 2025
657fc47
feat(docs): add summaries to all OpenAPI endpoints for better display…
alexhwoods Sep 27, 2025
7fd80ab
feat(docs): update examples to Hearth Furniture Company with North Am…
alexhwoods Sep 27, 2025
926b6e9
feat(docs): update domains to use proper TLDs (.com, .com.mx, .ca)
alexhwoods Sep 27, 2025
7412a30
feat(docs): standardize ID parameter names to entityId format
alexhwoods Sep 27, 2025
b0eebb8
feat(docs): add Bearer token format to AppAuth security scheme
alexhwoods Sep 27, 2025
2dcd5d6
feat(docs): add example to AppAuth security scheme
alexhwoods Sep 27, 2025
dd49e5b
feat(docs): use standard example field for AppAuth
alexhwoods Sep 27, 2025
46f4dc6
fix(docs): remove invalid example field from security scheme
alexhwoods Sep 27, 2025
7fc970e
feat(docs): use proper Bearer token security scheme with bearerFormat
alexhwoods Sep 27, 2025
d581107
fix(docs): use valid OpenAPI apiKey security scheme
alexhwoods Sep 27, 2025
84b15ec
feat(docs): add localhost:8020 server URL to OpenAPI spec
alexhwoods Sep 27, 2025
9b158f3
feat(docs): set templateId example to null for blank field
alexhwoods Sep 27, 2025
e0f12ac
feat(docs): remove templateId example to exclude from generated example
alexhwoods Sep 27, 2025
96a8d8c
feat(docs): set templateId example to empty string to prevent auto-ge…
alexhwoods Sep 27, 2025
74fc1b0
feat(docs): use x-mint hideInExample to hide templateId from examples
alexhwoods Sep 27, 2025
3c4ded3
feat(docs): hide locale field from examples with x-mint
alexhwoods Sep 27, 2025
6ea0387
fix(docs): correct path parameter name from {id} to {siteId} for Get …
alexhwoods Sep 27, 2025
9cca232
fix(docs): update path parameter names in docs.json to match OpenAPI …
alexhwoods Sep 27, 2025
5cd4fc5
feat(docs): add draft query parameter to GET page endpoint
alexhwoods Sep 27, 2025
00dc706
fix(docs): standardize path parameter names to entityId format
alexhwoods Sep 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 113 additions & 51 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,6 @@
"developer/guides/how-to/set-cookies",
"developer/guides/how-to/add-custom-fonts"
]

},
{
"group": "Troubleshooting",
Expand Down Expand Up @@ -207,64 +206,127 @@
"group": "Reference",
"pages": [
{
"group": "Components",
"group": "@makeswift/runtime",
"pages": [
"developer/reference/components/page",
"developer/reference/components/makeswift-component",
"developer/reference/components/slot",
"developer/reference/components/react-runtime-provider",
"developer/reference/components/root-style-registry"
]
},
{
"group": "Controls",
"pages": [
"developer/reference/controls/checkbox",
"developer/reference/controls/color",
"developer/reference/controls/combobox",
"developer/reference/controls/group",
"developer/reference/controls/image",
"developer/reference/controls/font",
"developer/reference/controls/link",
"developer/reference/controls/list",
"developer/reference/controls/number",
"developer/reference/controls/rich-text",
"developer/reference/controls/select",
"developer/reference/controls/slot",
"developer/reference/controls/style",
"developer/reference/controls/text-area",
"developer/reference/controls/text-input",
{
"group": "Deprecated",
"pages": ["developer/reference/controls/shape"]
"group": "Components",
"pages": [
"developer/reference/components/page",
"developer/reference/components/makeswift-component",
"developer/reference/components/slot",
"developer/reference/components/react-runtime-provider",
"developer/reference/components/root-style-registry"
]
},
{
"group": "Controls",
"pages": [
"developer/reference/controls/checkbox",
"developer/reference/controls/color",
"developer/reference/controls/combobox",
"developer/reference/controls/group",
"developer/reference/controls/image",
"developer/reference/controls/font",
"developer/reference/controls/link",
"developer/reference/controls/list",
"developer/reference/controls/number",
"developer/reference/controls/rich-text",
"developer/reference/controls/select",
"developer/reference/controls/slot",
"developer/reference/controls/style",
"developer/reference/controls/text-area",
"developer/reference/controls/text-input",
{
"group": "Deprecated",
"pages": ["developer/reference/controls/shape"]
}
]
},
{
"group": "Client",
"pages": [
"developer/reference/client/constructor",
"developer/reference/client/get-pages",
"developer/reference/client/get-page-snapshot",
"developer/reference/client/get-component-snapshot",
"developer/reference/client/get-site-version"
]
},
"developer/reference/makeswift-api-handler",
{
"group": "ReactRuntime",
"pages": [
"developer/reference/runtime/constructor",
"developer/reference/runtime/register-component"
]
},
{
"group": "Functions",
"pages": ["developer/reference/get-site-version"]
},
{
"group": "Legacy APIs",
"pages": ["developer/reference/client/get-sitemap"]
}
]
},
{
"group": "Client",
"group": "REST API",
"openapi": {
"source": "openapi.yaml"
},
"pages": [
"developer/reference/client/constructor",
"developer/reference/client/get-pages",
"developer/reference/client/get-page-snapshot",
"developer/reference/client/get-component-snapshot",
"developer/reference/client/get-site-version"
]
},
"developer/reference/makeswift-api-handler",
{
"group": "ReactRuntime",
"pages": [
"developer/reference/runtime/constructor",
"developer/reference/runtime/register-component"
{
"group": "Sites",
"pages": [
"POST /v1/workspaces/{workspaceId}/sites",
"GET /v1/workspaces/{workspaceId}/sites",
"GET /v1/sites/{siteId}",
"PATCH /v1/sites/{siteId}",
"DELETE /v1/sites/{siteId}",
"POST /v1/sites/{siteId}/duplicate"
]
},
{
"group": "Locales",
"pages": [
"POST /v1/sites/{siteId}/locales",
"GET /v1/sites/{siteId}/locales",
"GET /v1/locales/{localeId}",
"PATCH /v1/locales/{localeId}",
"DELETE /v1/locales/{localeId}"
]
},
{
"group": "Pages",
"pages": [
"POST /v1/sites/{siteId}/pages",
"GET /v0/sites/{siteId}/pages",
"GET /v1/sites/{siteId}/pages/{pageId}",
"PATCH /v1/sites/{siteId}/pages/{pageId}",
"DELETE /v1/sites/{siteId}/pages/{pageId}"
]
},
{
"group": "Routes",
"pages": [
"POST /v1/sites/{siteId}/routes",
"GET /v1/sites/{siteId}/routes",
"GET /v1/routes/{routeId}",
"PATCH /v1/routes/{routeId}",
"DELETE /v1/routes/{routeId}"
]
},
{
"group": "Webhooks",
"pages": [
"POST /v1/workspaces/{workspaceId}/webhooks",
"GET /v1/workspaces/{workspaceId}/webhooks",
"GET /v1/webhooks/{webhookId}",
"DELETE /v1/webhooks/{webhookId}"
]
}
]
},
{
"group": "Functions",
"pages": ["developer/reference/get-site-version"]
},
{
"group": "Legacy APIs",
"pages": ["developer/reference/client/get-sitemap"]
}
]
},
Expand Down
Loading