01 · Develop

Your spec, as code you can run.

Specbook turns your OpenAPI file into typed operations you can use directly in TypeScript. Write requests and flows with autocomplete and type checking for every path, query, and body, and run them as you write.

Add your spec

Install the CLI, create a project and add your OpenAPI file or an address. Specbook generates a typed operation for every endpoint.

npm install --save-dev @specbook/cli @specbook/core

$ specbook init

Write a request

A request calls one operation. Your editor autocompletes the path, query, and body from the spec, and your checks decide what counts as a pass.

export default GetPetById.request({
  name: 'Get a pet',
  tags: ['smoke', 'monitor'],
  path: { petId: '{{petId}}' },
  init: { petId: 1 },
  assert: (res, { assert, vars }) => {
    assert.is(res.status, 200, 'found')
    if (res.status === 200) assert.is(res.data.id, Number(vars.petId), 'the pet that was asked for')
  },
})

Chain requests into a flow

A flow runs requests in order, and each step can use what the one before it returned. The types come from your spec, so a misspelt field is caught as you type, not at run time.

export default sequence({
  id: 'adopt-pet',
  title: 'Adopt a pet',
  description: 'Find available pets, pick one, order it, then verify the order.',
  tags: ['petstore', 'smoke'],
  inputs: {
    quantity: c.number({ default: 1, min: 1, description: 'How many of the chosen pet to order.' }),
  },
})
  .step('Find available pets', findPets) // keeps the pets the response lists
  // QA picks a pet in the portal. An automated run is not asked and takes the first one
  .input('Choose a pet', (ctx) => ({
    petId: c.select(ctx.captured.pets, {
      label: (p) => `${p.name} (#${p.id})`,
      value: (p) => p.id as number,
      default: 0,
    }),
  }))
  .step('Place order', placeOrder) // sends the chosen petId and the quantity
  .step('Verify order', getOrder) // the order id from the last step is already filled in

Run it as you write

Run specbook dev to try every request and flow in a play panel beside your docs. No API yet? The mock environment answers from your spec's examples, so you can start anyway. The same files run from the terminal.

npx specbook dev                      # try requests and flows in a play panel
npx specbook test                     # run them all, against mock data
npx specbook test --env staging       # run them all, against a real environment

Publish it

Share what you wrote. QA gets a portal, your docs get Try it buttons, and production gets a single file that only needs node.

npx specbook build --minimal    # a portal with just your requests and flows, for QA
npx specbook build              # your docs, plus a script that makes any button run a request
npx specbook bundle             # your tests as one file that needs only node