How do we use Speakeasy to generate a mock server from our OpenAPI spec for SDK and integration tests?

Most teams hit the same wall: you can generate SDKs from your OpenAPI spec, but actually verifying them without a live backend is painful. A mock server gives you stable, predictable responses so you can run SDK and integration tests on every commit—without waiting on backend deployments.

Quick Answer: Speakeasy doesn’t yet ship a one-click “generate mock server” command, but you can use your OpenAPI spec plus Speakeasy’s generated SDKs/CLIs to build a reliable mock server workflow for SDK and integration tests. The core pattern is: treat your OpenAPI as the contract, auto-generate client interfaces, and stand up a mock service (local or CI) that returns spec-valid responses and is easy to script in tests.

---

Frequently Asked Questions

Can Speakeasy directly generate a mock server from my OpenAPI spec?

Short Answer: Today, Speakeasy focuses on generating SDKs, CLIs, Terraform providers, and MCP servers from your OpenAPI spec—not a fully managed mock server. You can, however, use those generated artifacts plus your spec to run reliable mock-based SDK and integration tests.

Expanded Explanation:
Speakeasy’s core workflow starts with your OpenAPI spec and generates the interfaces your consumers actually use: idiomatic SDKs in 7+ languages, CLIs, Terraform providers, and MCP servers. That same OpenAPI contract is exactly what a mock server needs: routes, parameters, schemas, and response shapes.

While there isn’t a dedicated speakeasy generate mock-server command today, most teams pair Speakeasy with a lightweight mock service (e.g., a small Node/Go service, an API gateway mocking mode, or an OpenAPI mock tool) and then point their Speakeasy-generated SDKs/CLIs at that mock base URL for tests. The result: you can continuously validate that your generated SDKs and tools stay in lockstep with the spec before your backend rolls out changes.

Key Takeaways:

• Speakeasy doesn’t currently provide a first-class mock server generator, but it does give you all the client-side pieces wired to your spec.
• The recommended pattern is: use OpenAPI as the single source of truth, generate SDKs/CLIs, and stand up a simple mock server that returns spec-valid responses for SDK and integration tests.

---

How do I set up a mock-server workflow with Speakeasy for SDK and integration tests?

Short Answer: Use your OpenAPI spec as the contract, generate SDKs/CLIs with Speakeasy, and run them against a mock server (local or in CI) that serves predictable responses defined by the same spec.

Expanded Explanation:
Speakeasy’s strength is operationalizing change: “APIs change fast. Your SDKs should too.” Mocking is just another place you want that same discipline. The workflow is:

1. Treat your OpenAPI spec as the source of truth.
2. Generate SDKs and CLIs from it with Speakeasy.
3. Run those SDKs/CLIs in tests against a mock server that is trivial to reset, seed, and inspect.

You can build the mock server itself however you like (custom service, gateway mocking mode, third-party OpenAPI mock), but the key is keeping it aligned with your spec. Because Speakeasy consumes your OpenAPI, the same contract that defines the mock also defines the SDK types and request builders. That’s what keeps “it works in tests” and “it works in production” from drifting.

Steps:

1. Upload your OpenAPI and generate SDKs
   • Install the Speakeasy CLI (e.g., via Homebrew):

     brew install speakeasy-api/tap/speakeasy
     

   • Use the CLI or app to upload/point at your OpenAPI and generate SDKs (TypeScript, Python, Go, Java, C#, PHP, and more).
2. Stand up a mock server from your spec
   • Use your preferred approach (e.g., a local Node/Go mock, gateway mocking, or an OpenAPI mock tool) that reads the same spec and exposes the same paths.
3. Wire your tests to the mock server using Speakeasy-generated clients
   • Configure the SDK base URL to point at the mock server.
   • In CI, spin up the mock service before tests run, then execute your SDK and integration tests against it.

---

What’s the difference between using a mock server vs a real backend for SDK and integration tests?

Short Answer: A mock server gives you stability and speed; a real backend gives you full realism and side effects. For SDK and contract tests, the mock is usually best. For full end-to-end flows and data behavior, you still need the real backend.

Expanded Explanation:
If you only test against a real backend, you’re at the mercy of deployments, migrations, data drift, and rate limits. That’s how you end up with flaky test suites and slow feedback loops. A mock server, on the other hand, lets you:

• Pin responses to specific shapes and error codes.
• Run tests without touching shared environments.
• Reset state instantly between runs.

The trade-off is that mocks don’t validate everything—especially complex business rules or cross-service behavior. That’s why most teams do both: use a mock server for fast, deterministic SDK and contract tests, and a smaller set of end-to-end tests against a real environment.

Comparison Snapshot:

• Mock server: Fast, deterministic, easy to seed/reset; perfect for validating SDK correctness, request building, and error handling against the OpenAPI contract.
• Real backend: Full fidelity, real data and side effects; essential for validating workflows, auth, and system behavior under load.
• Best for:
  • Mock server: SDK tests, CLI tests, CI contract tests on every commit.
  • Real backend: Staging or pre-prod smoke tests, performance tests, and business-logic validation.

---

How do I practically wire my Speakeasy-generated SDKs and CLIs to a mock server?

Short Answer: Configure the SDK/CLI to use your mock server’s base URL in your test environment, then run your test suite against that endpoint. You’ll exercise the same generated code you ship to consumers, just pointed at a controlled backend.

Expanded Explanation:
Speakeasy-generated SDKs are built to be configuration-driven: you set the base URL, auth, and other client options at initialization. That makes swapping a real backend for a mock server a single line of configuration. Similarly, Speakeasy-generated CLIs are standard Go binaries with flags and environment variable support, so you can direct them to your mock server from CI.

This is the pattern you want to operationalize:

• Local dev: Run SDK unit tests against mocks, and optionally an integration suite against a mock server.
• CI: Start your mock service, point SDK/CLI to it, and run the full integration test matrix.
• Staging/prod: Same SDKs and CLIs, but configured against real environments.

What You Need:

• An OpenAPI spec that matches your mock server routes and payloads.
• Speakeasy-generated SDKs and/or CLI, with environment-based configuration for the base URL (e.g., API_BASE_URL or similar).

Example rough wiring (TypeScript SDK):

import { Client } from "./generated-sdk";

const client = new Client({
  serverURL: process.env.API_BASE_URL ?? "http://localhost:8080",
  // mock server for tests; real URL in staging/prod
});

test("creates a resource using the mock server", async () => {
  const res = await client.resources.create({ name: "test" });
  expect(res.statusCode).toBe(201);
  expect(res.resource?.name).toBe("test");
});

In CI, you’d set:

export API_BASE_URL="http://mock-server:8080"
npm test

---

How does this mock-server approach help with long-term SDK quality and integration reliability?

Short Answer: It lets you “ship with every commit” confidently by catching contract breaks early—before they hit consumers—using the same OpenAPI-driven generation flow Speakeasy uses for SDKs and tools.

Expanded Explanation:
The real pain point isn’t just “can I mock this endpoint?” It’s “how do I keep SDKs, CLIs, Terraform, and now MCP tools in sync as the API evolves?” That’s where an OpenAPI-centric, mock-aware workflow pays off:

• You update the OpenAPI spec first.
• Speakeasy regenerates SDKs/CLIs/other artifacts via CI pull requests.
• Your mock server (or mock harness) is driven off the same spec.
• Tests run against the mock on every commit or PR, catching breaking changes immediately.

This is how teams using Speakeasy report they “accelerated our release schedule without sacrificing code quality.” You’re not manually updating SDKs or manually changing mocks; you’re updating the spec and letting automation do the rest. For agents and MCP, you can apply the same pattern: compact, predictable tool interfaces backed by observable, governable infrastructure.

Why It Matters:

• Fewer regressions: Contract-breaking changes surface as failing SDK/integration tests tied directly to your OpenAPI spec.
• Faster releases: Automated generation + mock-based checks mean you can merge confidently and publish SDK updates on every commit without manual QA bottlenecks.

---

Quick Recap

Using Speakeasy to generate a mock-server workflow isn’t about a single “mock server” button—it’s about treating your OpenAPI spec as the shared contract across SDKs, CLIs, and your mock backend. Generate your clients from the spec, stand up a spec-aligned mock server, and run SDK and integration tests against it in CI. That’s how you keep pace with fast-changing APIs while preserving DX and reliability.

Next Step

Get Started