stuntman / providers / openapi

OpenAPI

Give Stuntman the provider's OpenAPI or Swagger spec and it answers like the API: routes, answers, schema checks and the token route.

Stands in for

  • OpenAPI 3.0 and 3.1
  • Swagger 2.0
  • JSON or YAML specs with $ref files
  • OAuth2 client-credentials token URLs
  • OpenAPI webhooks and callbacks

Everything OpenAPI gives you

  1. 01

    A route per operation

    Each path and method becomes a route with the server's base path in front; the operationId is kept.

  2. 02

    Answers from the spec

    The lowest 2xx is the default; every other response becomes a named answer like payment_required or not_found.

  3. 03

    Built when no example

    From the schema: ids that change per call, now() for date-time, and fields that echo what the app sent.

  4. 04

    Bodies checked

    Types, required, enums, allOf, oneOf, additionalProperties: false and date, date-time, email formats; a bad body gets the spec's 400 or 422.

  5. 05

    Token route included

    OAuth2 client credentials in the spec add a token route at its tokenUrl; routes using it require a Bearer token.

  6. 06

    Webhooks ready to send

    3.1 webhooks and 3.0 callbacks become webhook_<name> answers holding their payloads.

  7. 07

    The spec served back

    Kept with the files its $refs point to, so clients generated from it work unchanged.

  8. 08

    Re-import keeps edits

    A new version adds routes; your steps, answers, data and settings stay. Routes it lacks are listed in notInSpec.

The screens

Each number is a control or a reading on the real screen. Everything you can click there, your agent can do with a tool.

A new service from a spec

A new service from a spec: the OpenAPI screen in Stuntman
1Start from a spec

OpenAPI 3.x, Swagger 2.0 or a WSDL; Stuntman tells which one it is.

1 of 5
2URL or file

Files the spec points to with $ref are read too.

2 of 5
3Check bodies

A body that breaks the schema gets the provider's 400 error.

3 of 5
4What the spec has

Every route with the responses it declares, before anything is created.

4 of 5
5OAuth from securitySchemes

Client credentials on /oauth/token, any client accepted until you add some.

5 of 5
  1. Start from a spec

    OpenAPI 3.x, Swagger 2.0 or a WSDL; Stuntman tells which one it is.

  2. URL or file

    Files the spec points to with $ref are read too.

  3. Check bodies

    A body that breaks the schema gets the provider's 400 error.

  4. What the spec has

    Every route with the responses it declares, before anything is created.

  5. OAuth from securitySchemes

    Client credentials on /oauth/token, any client accepted until you add some.

Routes made from the spec are normal routes

Routes made from the spec are normal routes: the OpenAPI screen in Stuntman
1Routes from the spec

One per operation, with calls today.

1 of 5
2Receive

Bearer token from /oauth/token; the body is checked against ChargeRequest, else the invalid answer.

2 of 5
3Decide

Rules you add pick the spec's other responses: a card ending 0002 gets 402.

3 of 5
4Re-import the spec

Reads a new version and keeps your steps; the served spec is one click away.

4 of 5
5Path it lacks

A call to a path the spec does not have shows in Unmatched.

5 of 5
  1. Routes from the spec

    One per operation, with calls today.

  2. Receive

    Bearer token from /oauth/token; the body is checked against ChargeRequest, else the invalid answer.

  3. Decide

    Rules you add pick the spec's other responses: a card ending 0002 gets 402.

  4. Re-import the spec

    Reads a new version and keeps your steps; the served spec is one click away.

  5. Path it lacks

    A call to a path the spec does not have shows in Unmatched.

Answers from the spec's responses

Answers from the spec's responses: the OpenAPI screen in Stuntman
1One per response

Marked example (the spec's example) or schema (built from the schema).

1 of 5
2Reset to the spec

Edit an answer to match the real provider, or go back to what the spec said.

2 of 5
3Checked against the schema

The body is a template checked against the response schema.

3 of 5
4Timeline sentence

What the call leaves on the timeline, as a template.

4 of 5
5What the app gets

Status, headers and body, filled from the last call.

5 of 5
  1. One per response

    Marked example (the spec's example) or schema (built from the schema).

  2. Reset to the spec

    Edit an answer to match the real provider, or go back to what the spec said.

  3. Checked against the schema

    The body is a template checked against the response schema.

  4. Timeline sentence

    What the call leaves on the timeline, as a template.

  5. What the app gets

    Status, headers and body, filled from the last call.

Break it on purpose

The failures you need to test, exactly when you ask: from the screen or by a tool call, each one shown on the timeline with who caused it.

  • Any declared response

    402, 404, 409 or any response the spec declares, on the next calls

    force_answer payment_required
  • Validation error

    A body that breaks the schema gets the spec's 400 or 422 naming the field

    send a bad body
  • Expired token

    Every token becomes invalid; the next call gets 401

    expire_tokens
  • Missing token

    A route that uses the OAuth scheme refuses a call without Bearer

    call without a token
  • Undeclared response

    An answer the spec does not have

    set_answer
  • Network and server failures

    Reset, empty, timeout, 500, 503 or an HTML page

    force_answer
  • Slow or flaky

    Latency on every answer, or a random share of failures

    set_service latency, fail_share
  • Path not in the spec

    The app calls a version the spec lacks; it answers 404 no route

    list_unmatched

Why not the real sandbox

Your AI agent drives it

Claude Code, Codex or any MCP client connects to /mcp (or calls /api over plain HTTP), sets the stand-in up, breaks it on cue and reads what your app did.

you

Stand in for the payments API from its OpenAPI spec and test a declined card at checkout.

import_spec{"service": "example-payments", "source": "https://api.payments.example.com/openapi.yaml"}
→ ok 5 routes, 10 answers, 1 webhook
force_answer{"service": "example-payments", "answer": "payment_required", "route": "POST /v1/charges", "count": 1}
wait_for_api_call{"service": "example-payments", "route": "POST /v1/charges"}
→ ok 402 payment_required went to the app

MCP tools

  • import_specA service from OpenAPI 3.x, Swagger 2.0 or a WSDL
  • reimport_specReads the spec again and keeps your steps
  • list_answersNamed answers and which route uses each
  • set_answerCreates or replaces a named answer
  • set_routeCreates or replaces a route
  • try_routeRuns a route on a sample request
  • force_answerThe next calls get a named answer
  • expire_tokensEvery token becomes invalid
  • list_unmatchedCalls to paths no route takes

The same over HTTP

  • POST/api/plugins/spec
  • POST/api/plugins/{service}/spec
  • GET/api/plugins/{service}/answers
  • POST/api/plugins/{service}/try
  • POST/api/plugins/{service}/tokens/expire