Skip to content

feat: docs tab shows each response, and author pages place the generated blocks - #21

Merged
ajaishankar merged 8 commits into
mainfrom
feat/docs-responses
Oct 23, 2026
Merged

ajaishankar merged 8 commits into
mainfrom
feat/docs-responses

Conversation

@ajaishankar

Copy link
Copy Markdown
Member

What

The Docs tab now documents the whole operation from the spec, and an author's markdown page decides where each part goes.

  • Responses: one tab per status, with the spec's description, the body type and a field table. Examples stay on the Try tab ("Respond with").
  • Field tables: top level only. A field with children has a [+] box and the whole row opens it. Its plain fields sit one step in, and each object among them is its own group at the left under its whole path (address.county). Nothing indents further than one step, so phones stay readable. The same table serves parameters, the request body and responses, including root arrays and root unions.
  • Codegen: each response's description and media type go into the per-operation docs file. Older generated output still works.
  • Author pages: write any markdown, and place a block with <!-- specbook: body --> on a line of its own. Names: description, auth, params, path, query, headers, body, responses, examples. Blocks left unplaced follow the page in the old order.
  • Descriptions written in HTML (Stripe's <p>…</p>) are read as the markdown they mean, with the same escaping as before.
  • New reference page on the docs site: Documentation pages.

Breaking change (release notes)

Field-note headings such as ## `petId` no longer attach to a field. They show as ordinary text. Field descriptions come from the spec. Move the sentence into the spec or into the page, and place the table with a comment. The docs site reference page has the migration note.

Size

Embed budgets still pass: 103 KB and 143 KB gzip against 105 and 145, about 1 KB over before. The comment in the test is updated.

Tests

Codegen, vite, ui unit, browser, viewer, embed budgets and docs-site end-to-end all pass locally. Not yet looked at on a phone by hand: only the automated phone-width test covers it.

🤖 Generated with Claude Code

ajaishankar and others added 8 commits October 22, 2026 23:54
…ocs page

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…nd author pages place the blocks

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…d tables go

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…bject as a group of its own

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…vron stays on its name's line

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…d [−] mark it

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@ajaishankar ajaishankar changed the title feat: Docs tab shows each response, and author pages place the generated blocks feat: docs tab shows each response, and author pages place the generated blocks Oct 23, 2026
@ajaishankar
ajaishankar merged commit ec846af into main Oct 23, 2026
4 checks passed
@ajaishankar
ajaishankar deleted the feat/docs-responses branch October 23, 2026 06:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant