From e09f64b4f2b7b3f9bca838a041005f63053265c8 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 8 Sep 2026 19:17:05 +0000 Subject: [PATCH] docs(spec): fence the endpoint listings in the automation and package API docblocks `api/automation-api` and `api/package-api` captioned a listing with `@example Endpoints` and then wrote its rows as ordinary prose lines. Consecutive non-blank lines are one markdown paragraph and the docs site loads no `remark-breaks`, so each soft break rendered as a space and both pages published their whole listing as one run-on line with the author's column alignment collapsed. Fence both listings at the source, exactly as the neighbouring `api/odata` and `api/metadata` docblocks already do, and regenerate the two reference pages. The renderer is not touched: it preserves the source's own line layout deliberately, and a rule that guessed which prose runs are really tables is the shape-sniffing its header rejects. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_016N6xmWt5hYm94ffVEwGH8x --- .changeset/fence-api-endpoint-listings.md | 9 +++++++++ content/docs/references/api/automation-api.mdx | 2 ++ content/docs/references/api/package-api.mdx | 2 ++ packages/spec/src/api/automation-api.zod.ts | 2 ++ packages/spec/src/api/package-api.zod.ts | 2 ++ 5 files changed, 17 insertions(+) create mode 100644 .changeset/fence-api-endpoint-listings.md diff --git a/.changeset/fence-api-endpoint-listings.md b/.changeset/fence-api-endpoint-listings.md new file mode 100644 index 0000000000..306cf920d4 --- /dev/null +++ b/.changeset/fence-api-endpoint-listings.md @@ -0,0 +1,9 @@ +--- +"@objectstack/spec": patch +--- + +The `api/automation-api` and `api/package-api` reference pages publish their endpoint listing as a code block instead of a run-on line. + +Both module docblocks captioned a listing with `@example Endpoints` and then wrote its rows as ordinary prose lines. Consecutive non-blank lines are one markdown paragraph, and the docs site loads no `remark-breaks`, so every soft line break became a space: the nine automation rows and the eight package rows each arrived as a single run-on sentence with the author's column alignment collapsed away. The listings are now fenced at the source, the way the neighbouring `api/odata` and `api/metadata` docblocks already fence theirs, and the two generated pages render a block. + +The fix is in the two `.zod.ts` docblocks — which ship to consumers under this package's `src/**/*.zod.ts` — and in the pages regenerated from them. No schema, export, accept set or runtime behaviour changes. diff --git a/content/docs/references/api/automation-api.mdx b/content/docs/references/api/automation-api.mdx index 1fa9d72e43..183ac040e1 100644 --- a/content/docs/references/api/automation-api.mdx +++ b/content/docs/references/api/automation-api.mdx @@ -13,6 +13,7 @@ triggering executions, and querying execution history. Base path: /api/automation **Endpoints** +``` GET /api/automation — List flows GET /api/automation/:name — Get flow POST /api/automation — Create flow @@ -22,6 +23,7 @@ POST /api/automation/:name/trigger — Trigger flow execution POST /api/automation/:name/toggle — Enable/disable flow GET /api/automation/:name/runs — List execution runs GET /api/automation/:name/runs/:runId — Get single execution run +``` **Source:** `packages/spec/src/api/automation-api.zod.ts` diff --git a/content/docs/references/api/package-api.mdx b/content/docs/references/api/package-api.mdx index 38c8801550..6de0850dfd 100644 --- a/content/docs/references/api/package-api.mdx +++ b/content/docs/references/api/package-api.mdx @@ -12,6 +12,7 @@ REST API endpoint schemas for package lifecycle management. Base path: /api/v1/packages **Endpoints** +``` POST /api/v1/packages/install — Install a package POST /api/v1/packages/upgrade — Upgrade a package POST /api/v1/packages/resolve-dependencies — Resolve dependencies @@ -20,6 +21,7 @@ GET /api/v1/packages — List installed packages GET /api/v1/packages/:packageId — Get package details POST /api/v1/packages/:packageId/rollback — Rollback a package DELETE /api/v1/packages/:packageId — Uninstall a package +``` **Source:** `packages/spec/src/api/package-api.zod.ts` diff --git a/packages/spec/src/api/automation-api.zod.ts b/packages/spec/src/api/automation-api.zod.ts index 681d183cb1..0d57bc4ca3 100644 --- a/packages/spec/src/api/automation-api.zod.ts +++ b/packages/spec/src/api/automation-api.zod.ts @@ -14,6 +14,7 @@ import { ExecutionLogSchema, ExecutionStatus, FlowRunSummarySchema } from '../au * Base path: /api/automation * * @example Endpoints + * ``` * GET /api/automation — List flows * GET /api/automation/:name — Get flow * POST /api/automation — Create flow @@ -23,6 +24,7 @@ import { ExecutionLogSchema, ExecutionStatus, FlowRunSummarySchema } from '../au * POST /api/automation/:name/toggle — Enable/disable flow * GET /api/automation/:name/runs — List execution runs * GET /api/automation/:name/runs/:runId — Get single execution run + * ``` */ // ========================================== diff --git a/packages/spec/src/api/package-api.zod.ts b/packages/spec/src/api/package-api.zod.ts index 2b4dd050ff..cd68a6684a 100644 --- a/packages/spec/src/api/package-api.zod.ts +++ b/packages/spec/src/api/package-api.zod.ts @@ -17,6 +17,7 @@ import { ArtifactReferenceSchema } from '../cloud/marketplace.zod'; * Base path: /api/v1/packages * * @example Endpoints + * ``` * POST /api/v1/packages/install — Install a package * POST /api/v1/packages/upgrade — Upgrade a package * POST /api/v1/packages/resolve-dependencies — Resolve dependencies @@ -25,6 +26,7 @@ import { ArtifactReferenceSchema } from '../cloud/marketplace.zod'; * GET /api/v1/packages/:packageId — Get package details * POST /api/v1/packages/:packageId/rollback — Rollback a package * DELETE /api/v1/packages/:packageId — Uninstall a package + * ``` */ // ==========================================