Skip to main content
APIWeave
Download

Guide

Turn an API definition into an API test

An OpenAPI or Swagger document already describes every endpoint, parameter, and body shape your API accepts. APIWeave reads it and puts those operations on the canvas as ready-to-run request nodes — which leaves you the part that is actually a test: the assertions.

Download APIWeave

What you get

Requests from the spec, assertions from you

The importer removes the transcription. It does not decide what a correct response is — that stays a judgement about your contract.

A workflow built from an imported spec
[ Start ]
  -> [ GET /users/:id       imported from the spec ]
  -> [ Assertion: status == 200 ]
  -> [ GET /users/:id/orders   imported from the spec ]
  -> [ Assertion: body.items count == 3 ]
  -> [ End ]
What an imported node carries
GET {{env.BASE_URL}}/users/:id

  path variables:  id = {{variables.userId}}
  headers:         Authorization: Bearer {{secrets.API_KEY}}
  query params:    include = orders

Imported from the spec with its method, URL, parameters, and body shape.
Placeholders still work in every field, so the node is runnable against
the selected environment with no further wiring.

Each imported template arrives pre-filled with the method, URL, parameters, and body shape from its operation. Drag it onto the canvas and it is a real HTTP Request node, not a locked-down import artifact — edit headers, add extractors, attach assertions, set an expected status.

Imported templates are starting points. The value the importer adds is that a request matches the published contract on the first try; the value you add is knowing which fields must hold for the API to be working.

Assertion nodes cover status, headers, cookies, variables, and the previous response, with pass and fail edges, so a broken contract takes its own path through the graph instead of stopping the run.

Two import paths

Sync against a live spec, or load a file once

Pick by whether the definition keeps moving.

Environment-linked sync

Best when: The definition changes and you want the templates to keep up.

How: Pin the spec URL on an environment. Refresh in the canvas toolbar re-fetches it and rebuilds the imported group. Swapping environments swaps specs.

You must keep the URL on the environment current if the API team moves the document.

One-time file import

Best when: You have a spec on disk and want a batch of templates once.

How: Import → OpenAPI → upload a .json or .yaml file → Preview → optionally pick a server URL, filter by tags, or sanitize the body → Add to Nodes.

No ongoing sync and no drift badge. If the file changes, import it again.

Setting the environment-linked spec URL

The spec URL is a field on an environment, not a workflow setting. That is what lets staging and production carry different specs without touching the canvas.

Accepted URL shapes
Direct spec URL:         https://api.example.com/v3/api-docs
Direct spec URL:         https://api.example.com/swagger/v1/swagger.json
Swagger UI landing URL:  https://api.example.com/swagger-ui/index.html
Swagger UI landing URL:  https://api.example.com/webjars/swagger-ui/index.html

The URL is read by the desktop app's main process, not your browser,
so an internal or LAN host works without extra configuration.

Drift

The Check API badge, and what it does not mean

A spec refresh never rewrites a node you have edited. It tells you when the two have diverged and leaves the decision to you.

What a refresh does

  • Re-fetches the document and regenerates the imported group, so the latest spec is one drag away.
  • Compares canvas nodes that came from the same spec against the new operations.
  • Pins a Check API badge on any node that no longer matches, with the mismatch reason and the last successful refresh time.

What a badge does not mean

A badge is a drift finding, not a failing test. The node was never overwritten, and nothing about the run changed when the spec moved. Your options:

  • Bring the node in line: update the URL, method, or parameters to match the refreshed operation.
  • Leave it as it is. Calling a deprecated path on purpose is a legitimate reason for the node and the spec to disagree.

A one-time file import never generates badges, because there is no live document to compare against.

Formats

What the importer accepts

Both .json and .yaml documents, from a URL or a file.

Specification versions the importer supports
SpecificationSupported
OpenAPI 3.0Yes
OpenAPI 3.1Yes
Swagger 2.0Yes
Swagger 1.0No

A Swagger UI page that lists several definitions

Some gateways expose one page advertising more than one API definition. APIWeave discovers each one and imports operations from all of them into the same group, tagged with the definition name where one is available. If a definition fails to parse or fetch, the others still import and the failure is reported, so you can point the environment URL at the failing definition's direct spec URL to isolate it.

Troubleshooting

When an import does not work

The importer reports its own errors, so the fix is usually in the message.

“Select an environment before refreshing Swagger”
The importer reads the spec URL from the active environment. Pick one in the canvas toolbar.
“Environment has no Swagger/OpenAPI URL”
Open the Environments page, edit the active environment, and paste the spec URL into the OpenAPI/Swagger URL field.
“Failed to fetch Swagger URL”
The URL must start with http:// or https:// and be reachable from the desktop app, not just from your browser. If the Swagger UI page fails, try the direct spec URL.
Preview shows zero operations
The file is not a valid OpenAPI 3.x or Swagger 2.0 document. Check the top-level keys — openapi for 3.x, swagger: "2.0" for 2.0.

Once the requests are on the canvas, the next thing most people need is to pass a value from one into the next.

Chain requestsGetting started