Skip to content

<rapi-flow> draws a workflow on its own, or takes each API’s spec, server, credentials and mock from a <rapi-doc> or <rapi-doc-mini> on the page (see Standalone or paired).

An Arazzo document names the APIs its steps call in sourceDescriptions. <rapi-flow> lists them in the card above the diagram, under the Arazzo document’s URL (or the box that loads one): API sources, with each one’s name and URL (and its type when it is not openapi, such as another Arazzo document). The diagram’s first box then holds the workflow’s Inputs alone. A diagram drawn without the element (the portal’s {% workflow %} tag, renderArazzoWorkflow) lists them at the top of its first box instead, unless showSources: false is passed.

A document can name several sources (Rapid Parcels’ ship-a-parcel uses rates, shipments and tracking). Then:

  • Loading: <rapi-flow> fetches every openapi source, its URL taken relative to the Arazzo file. arazzo sources (other Arazzo documents) are listed but not loaded. A source that fails to load is listed under the diagram, and the steps on it show their operationId with “(not found)”.
  • Finding a step’s operation: an operationId is looked up in the sources in order, and the first that has it wins. When two APIs share an id, qualify it: $sourceDescriptions.shipments.createShipment. An operationPath ({$sourceDescriptions.<name>.url}#/paths/...) names its source.
  • A single paired <rapi-doc> shows one API: the first source (or the one whose spec it shows). <rapi-flow> takes that source from it (its processed spec, its selected server, its credentials) and loads the others itself. Clicking a step on another source does not scroll the reference, which does not have that operation. To show every API, pair one element per source (next section).
  • Runs: each source’s requests go to the server selected in its paired element, else the first server of its own spec; server-url replaces the first source’s. Credentials apply by security scheme id, across sources. An element’s in-browser mock answers the steps on its own source; steps on a source with no paired element, or whose element does not mock, go to their servers. With server-is-mock="true", those requests carry Prefer: code=, so a mock server that serves all the APIs (rapidoc mock serves a portal’s APIs side by side) answers them.
  • MCP export: one manifest source per loaded API; a workflow tool’s steps call each one at its own server.

for takes several ids separated by spaces, one element per OpenAPI source. Each element supplies its source’s spec, server, credentials and mock, and clicking a step shows its operation in the element of its source. <rapi-doc-mini> suits this best: <rapi-flow> sets its filter-operations to the shown workflow’s operations of its API, in step order, and updates it when the reader picks another workflow, so each mini lists just the calls the workflow makes.

<rapi-flow arazzo-url="/workflows/ship-a-parcel.arazzo.yaml" allow-arazzo-url-load="true"
for="rates-api shipments-api tracking-api"></rapi-flow>
<rapi-doc-mini id="rates-api" arazzo-source="rates" mock-server="true"></rapi-doc-mini>
<rapi-doc-mini id="shipments-api" arazzo-source="shipments" mock-server="true"></rapi-doc-mini>
<rapi-doc-mini id="tracking-api" arazzo-source="tracking" mock-server="true"></rapi-doc-mini>
  • Which element goes with which source: the source its arazzo-source attribute names; else the source whose URL it has loaded (spec-url, resolved against the page, equal to the source URL resolved against the Arazzo file); else the next source not taken, in document order. An element named for a source the document does not have is left alone, so a page can list elements for several Arazzo files in one for.
  • Loading: with allow-arazzo-url-load="true", <rapi-flow> loads each source into its element, so the elements need no spec-url: a <rapi-doc> loads it at once, a mini once its filter is set, so it is fetched filtered from the start. <rapi-flow> loads a mini’s source itself too, to resolve every workflow’s steps; a <rapi-doc>’s source is fetched only by the <rapi-doc>. Without the box, give each element its spec-url.
  • Changing for: <rapi-flow> pairs the elements again without loading the Arazzo file again. Elements are paired after flow-loaded fires, so a flow-loaded listener can create the elements for the document’s sources and set for. The multi-API example writes its three minis in the page instead, each with arazzo-source and spec-url, for Rapid Parcels’ ship-a-parcel.

With update-route="true", picking a workflow or clicking a step puts them in the address as query parameters:

/docs/shipping?workflow=shipParcel&step=label

Opening that link shows the shipParcel workflow, selects label, scrolls its box into view and shows its operation in the paired element, once that element has loaded its spec. Unknown ids are ignored.

  • Query parameters, not the hash: <rapi-doc> keeps the hash (#get-/pets) for its operations and rewrites it as the reader scrolls, so the two never overwrite each other. A link can carry both: ?workflow=shipParcel&step=label#get-/shipments/{shipmentId}/label.
  • No history entries: the address is replaced, as <rapi-doc> does, so Back leaves the page instead of stepping through clicks.
  • Routers: history.state is kept, so a single-page app’s router (Vue Router, React Router) keeps its data. In a router’s history mode both elements work as on a plain page. A hash-mode router owns the hash: set update-route="false" on <rapi-doc> there; <rapi-flow>’s parameters still work.
  • One element per page: the parameter names are fixed, so set it on one <rapi-flow> only.
  • A document loaded from the URL box drops the old step and shows its first workflow.