Repository navigation
Build the Management reference from the public spec - #335
Merged
Merged
Conversation
spec/mp.yaml is now the public spec generated upstream (make public-spec in the Management Platform repo): OpenAPI 3, with the server, authentication and the descriptions ported upstream from this repo's old copy. generate-mp-spec.ts reads it as OpenAPI 3: it names its own server, and the schema titles go on components.schemas. The new summaries rename one page: post-a-new-project is now create-a-project, with a redirect. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This was referenced Nov 2, 2026
dumitrugutu
approved these changes
Nov 2, 2026
mnemitz
added a commit
that referenced
this pull request
Nov 3, 2026
**Stack 3 of 4**, splitting #331 for review. Based on #335. 1. Site fixes (#334) 2. Management reference from the public spec (#335) 3. **Code samples, tested against a mock** ← this PR 4. API reference on Speculoos ## Changes - **Samples for every operation:** JavaScript, Python and curl for Batch (previously only `/jobs`), and curl for Management (previously none). - **One injector**, `scripts/code-samples/inject.ts`, adds them to both specs as `x-codeSamples`. `generate-batch-spec.ts` and `generate-mp-spec.ts` both use it, in place of Batch's own loop. - **`npm run test:code-samples`** runs 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 against `speechmatics-batch` through `uv`. - **An OpenAPI 3.1 copy of the Batch API for the tests:** `generate-openapi.ts` converts `static/batch.yaml` with `swagger2openapi`, then applies `spec/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 multipart `config` part being a `JobConfig`. 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. - **CI:** the `Code samples` workflow 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 build` passes, with no broken links. - The samples are in `static/batch.yaml` and `static/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](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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 2 of 4, splitting #331 for review. Based on #334.
Changes
spec/mp.yamlis the public spec generated upstream (make public-specin the Management Platform repo). It's OpenAPI 3, and it already includes what this repo's old Swagger 2.0 copy added: the server, authentication (a management token everywhere; either a token or an API key onPOST /api-keys), and the descriptions and summaries.generate-mp-spec.tsreads it as OpenAPI 3. The spec names its own server, so the generator no longer setsbasePath, and schema titles go oncomponents.schemas. The code-sample loop goes: there were no Management samples, and PR 3 adds them through one shared injector.post-a-new-project→create-a-project, with a redirect and the link inprojects.mdxupdated. I compared the generated page list withmain's, and nothing else changed.The pages still render through the current OpenAPI plugin. Most of the spec diff is upstream's generated output; the review points are the generator and the redirect.
Checked
npm run buildpasses, with no broken links.🤖 Generated with Claude Code