Show the sequence, not just the endpoints
<rapi-flow> draws the journeys an Arazzo document describes (find a pet, order it, read the order back) right next to your API reference, and lets readers run them against a mock or the real API, one lit-up step at a time.
Integrators Need the Order, Not Just the Operations
An API reference answers "what does this endpoint take?". The first question a new integrator asks is different: "which calls do I make, in which order, and what do I pass from one to the next?". That knowledge usually lives in a tutorial that drifts from the API. Arazzo puts it in a file next to the spec, and <rapi-flow>draws it from that file, so the diagram changes when the workflow does.
Forty operations, no path through them
- The order of calls is buried in prose, or in a sample app.
- Which response field feeds which request is left to the reader.
- Error handling ("retry when the store is busy") is a footnote, if it's there at all.
- Trying a journey means copying IDs between Try panels by hand.
The journey, drawn from the Arazzo file
- One box per step, in order, each linked to its operation in the reference.
- Dashed lines show each value a step passes on, labelled with its name.
goto,retryandendbranches are part of the diagram.- Run workflow makes every call, passes the values along and shows the outputs.
Run a Workflow Against the In-Browser Mock
The diagram below is tied to the Petstore reference beside it, which has mock-server="true": no backend answers, the page does. Pick what the mock should answer, then press Run workflow under the diagram and watch each step light up. Click a step to open its operation in the reference.
The mock answers every step with its success response. Press Run workflow.
The buttons fill the Mock Response Status table under the diagram: one row per step, plus a default. Edit it yourself to try other paths.
What It Draws
The layout is RapiDoc's own SVG code with no graph library, so the same diagram renders in the browser and, in a portal, as static SVG at build time.
Steps linked to operations
Each box names its step, method and path. Clicking it scrolls a tied <rapi-doc> to the operation.
Values passed between steps
A dashed line from findAvailable to placeOrder, labelled petId. Hover a value to see where it goes.
Success and failure branches
goto and retry draw as arrows back or forward; end closes the run. Each action shows its criteria.
Compact and expanded
Expanded shows each step's inputs and actions in its box; compact keeps only the operation, for long workflows.
Outputs at a glance
The workflow's outputs sit in a table under the steps, each with the step it comes from.
The Arazzo behind it
Steps name their operation by operationId (or operationPath); runtime expressions such as$response.body#/0/id and $steps.findAvailable.outputs.petId carry values from one step to the next.
arazzo: 1.0.1
info: { title: Petstore workflows, version: 1.0.0 }
sourceDescriptions:
- name: petstore
url: ./petstore.yaml
type: openapi
workflows:
- workflowId: adoptPet
summary: Adopt an available pet
inputs:
type: object
properties:
quantity: { type: integer, default: 1 }
steps:
- stepId: findAvailable
operationId: findPetsByStatus # a box linked to this operation
parameters:
- { name: status, in: query, value: available }
successCriteria:
- condition: $statusCode == 200
onFailure:
- { name: noPets, type: end } # the failure branch
outputs:
petId: $response.body#/0/id # passed on: a dashed line
- stepId: placeOrder
operationId: placeOrder
requestBody:
contentType: application/json
payload:
petId: $steps.findAvailable.outputs.petId
quantity: $inputs.quantity
onFailure:
- name: storeBusy
type: retry # drawn as a loop back
retryAfter: 2
retryLimit: 3
criteria:
- condition: $statusCode == 503
outputs:
orderId: $response.body#/id
outputs:
orderId: $steps.placeOrder.outputs.orderIdOne Workflow, Three Places It Runs
The run button, AI agents and the developer portal all use the same workflow runtime, built on RapiDoc's MCP manifest. A workflow that runs on this page runs the same way for an agent.
The run panel
Inputs with their defaults, credentials from the tied <rapi-doc> (or a small form of its own), a log with each step's request and response, and the outputs. Requests go from the reader's browser, likeTry.
One MCP tool per workflow
With a <rapi-flow for="…"> on the page, Export MCP Server adds a tool per workflow: its inputs become the arguments, its outputs the result. See the MCP guide.
Drawn at build time
@rapidoc/portal's {% workflow %} tag renders the diagram as static SVG, so it shows without JavaScript; the element loads only when a reader clicks Run workflow. The portal's hosted /mcp serves the same workflows to agents.
Add It to Your Docs
Load the flow bundle next to RapiDoc, point the element at your Arazzo file and tie it to the reference. Its attributes, events and CSS parts are in the reference docs.
<script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
<!-- A separate bundle: pages without workflows don't load it -->
<script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-flow-min.js"></script>
<rapi-flow
arazzo-url="/specs/petstore.arazzo.yaml"
workflow-id="adoptPet"
for="thedoc"
></rapi-flow>
<!-- The workflow borrows this element's spec, server, credentials and mock -->
<rapi-doc id="thedoc" spec-url="/specs/petstore.yaml" mock-server="true"></rapi-doc>Against a mock server, or the real API
For a mock that validates requests, generates data and checks OAuth scopes, run rapidoc mock and send the run there with server-url (or list it as a server in the spec and pick it in<rapi-doc>). Against the real API, the browser makes the calls, so the API must allow cross-origin requests from your docs site.
# A mock that validates requests, generates data and checks OAuth scopes
npx rapidoc mock # serves every spec under http://localhost:4010/<api id><rapi-flow
arazzo-url="/specs/petstore.arazzo.yaml"
spec-url="/specs/petstore.yaml"
server-url="http://localhost:4010/petstore"
></rapi-flow>See it next to a full API reference
The example page ties two Arazzo files to the Petstore reference, with branches, retries and the MCP export.