Repository navigation
Code samples for every Batch and Management operation, tested - #336
Merged
Merged
Conversation
Every Batch operation has JavaScript, Python and curl samples, and every Management operation a curl sample. One injector (scripts/code-samples/ inject.ts) adds them to both specs as x-codeSamples, which the reference renders as tabs. npm run test:code-samples runs each one against a mock built from the spec: requests are checked against the operation's schemas, and the mock answers with the spec's own examples. The Batch API's comes from an OpenAPI 3.1 copy (generate-openapi.ts converts static/batch.yaml and applies spec/batch.overlay.yaml, which adds a success example per operation and what Swagger 2.0 cannot express). The workflow runs the tests on any change to the specs, the samples or the harness, with a read-only token and no secrets. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
mnemitz
added a commit
that referenced
this pull request
Nov 3, 2026
mnemitz
added a commit
that referenced
this pull request
Nov 3, 2026
**Stack 4 of 4**, splitting #331 for review. Based on #336. 1. Site fixes (#334) 2. Management reference from the public spec (#335) 3. Code samples, tested against a mock (#336) 4. **API reference on Speculoos** ← this PR When the stack is merged, `main` matches #331's branch, minus `SPECULOOS-PLAN.md` (deleted here). ## What changes Every API reference page is rendered by [Speculoos](https://www.npmjs.com/package/@speculoos/react) (`0.1.0-alpha.1`) from IR built at build time (`npm run build:speculoos-ir`, wired into `start` and `build`). `scripts/generate-speculoos-pages.ts` writes one page per REST operation or WebSocket channel into gitignored directories, which the sidebar lists with `autogenerated`. A page's own prose, which the spec can't express (handshake responses, how a connection closes), lives in partials beside the pages. **Specs** - **Realtime** is rewritten as canonical AsyncAPI 3, with its authentication and WebSocket handshake declared. **Agent STT** is generated from it plus its overlay. - **Batch** renders from the OpenAPI 3.1 copy the code-sample tests already read (#336). **Management** renders from the public spec (#335). **Rendering** (`src/components/Speculoos/`) - `site.tsx`: how this site renders Speculoos. That's the Radix Themes map, with the site's Markdown, the sidebar's badge colours, and types expanded where they're used. - `SessionPanel.tsx`: a channel's session as a compact sequence diagram beside the reference, with each message linking to its section and showing its example on hover. Below `lg` it comes first, collapsed. - `OperationPanel.tsx`: an operation's code samples, then its examples, each labelled by its status's description ("400 Bad request"). - `Schema.tsx`: `<Schema>` puts the same field tables in guides, headed by the type's name and a link to where the reference uses it. `open` opens one field among the rest. The Batch and Realtime guides use it in place of the old `SchemaNode` and AsyncAPI loader. - The site's Markdown component moves to `src/components/Markdown`, on `react-markdown` 10 with `remark-gfm` 4 and `rehype-raw` 7. **Removed:** the OpenAPI plugin and theme, its templates and the sidebar filter for Batch paths, the `Schema`/`SchemaItem` theme components, the AsyncAPI and OpenAPI schema loaders, and the old WebSocket pages with their generator. ## Worth reviewing - **Redirects:** the Batch and Management info pages, the removed Batch log endpoint and `post-a-new-project` (from #335) are all in `redirects.json` / `vercel.json`. - **Anchors change:** message anchors are kebab-case now (`#startrecognition` → `#start-recognition`). In-repo links are updated, but external deep links to the old anchors will land at the top of the page; redirects can't cover fragments. - **CI builds from a clean checkout:** partials and `src/generated` are produced by the build, not committed. - **Speculoos is an alpha** from npm. `npm run speculoos:local` tries local packs of the Speculoos repo. ## Checked - `npm run build` passes, with no broken links. - `tsc` passes once the build has generated `src/generated`. - `npm run test:code-samples`: all 24 samples pass. Closes #331 once the stack lands. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stack 3 of 4, splitting #331 for review. Based on #335.
Changes
/jobs), and curl for Management (previously none).scripts/code-samples/inject.ts, adds them to both specs asx-codeSamples.generate-batch-spec.tsandgenerate-mp-spec.tsboth use it, in place of Batch's own loop.npm run test:code-samplesruns each sample against a mock built from the spec (scripts/code-samples/mock.ts). Requests are validated against the operation's schemas, and the mock answers with the spec's examples. JavaScript runs against@speechmatics/batch-client, and Python againstspeechmatics-batchthroughuv.generate-openapi.tsconvertsstatic/batch.yamlwithswagger2openapi, then appliesspec/batch.overlay.yaml(an OpenAPI Overlay 1.0). The overlay adds a success example per operation and what Swagger 2.0 can't express, such as the multipartconfigpart being aJobConfig. An action that matches nothing fails the build, so an upstream rename can't silently drop a patch. In PR 4 the reference renders from this same copy.Code samplesworkflow runs the tests on changes to the specs, samples or harness. It has a read-only token and no secrets, as pull requests from forks get anyway.Checked
npm run test:code-samples: all 24 samples pass.npm run buildpasses, with no broken links.static/batch.yamlandstatic/mp-api.yaml, under the same language labels as today. The plugin renders them client-side, and I haven't looked at them in a browser.🤖 Generated with Claude Code