02 · Document

Docs that run.

Write markdown beside every operation, or add Try it to any button on your existing documentation site. Readers send real requests without leaving the page, in your theme.

Write notes beside each operation

Put a markdown file next to what it describes. A README.md in an operation's folder documents that operation, and <name>.seq.md documents the flow beside it. A heading made of one code span, like ## `petId`, attaches its text to that field.

Looks a pet up by its id. Use this to check that a pet you added is really there.

## `petId`

The pet's number, as `Add a pet` returned it. The demo's seed pets are 1 to 3, and ones you add start at 1001.

What a reader sees

Make any example runnable

Load one script on your documentation site and add a data attribute. A plain element gets a Play button beside it, and a button or link that carries the attribute opens the panel itself.

<p data-specbook-try="petstore/GetPetById">Fetch a pet.</p>
<button type="button" data-specbook-flow="adopt-pet" data-specbook-inputs='{"quantity":2}'>
  Adopt two
</button>
<script type="module" src="/specbook/specbook.js"></script>

On this page, it does this

Fetch a pet by its id and see the response checked against the spec.

It looks like your site

The panel is isolated from your page, so neither can break the other. It uses your colors, follows your light or dark theme as it changes, and keeps what a visitor types out of your storage. Every attribute and variable is in the reference.

:root {
  --sb-accent: #e11d48;
  --sb-accent-hover: #be123c;
  --sb-font-sans: "Inter", system-ui, sans-serif;
  --sb-radius-card: 14px;
}