Proposal: openapi-msw library as a lightweight wrapper around MSW

[christoph-fricke]

Mock Service Worker (MSW) is a popular library for defining HTTP mocks that can be used quite flexibly. It is great for mocking APIs in all kind of tests or during development.

Using openapi-typescript and openapi-fetch enables use to ensure that our application's API client does not have conflicts with the API specification, which is great. However, while we can address issues with the API client, we have to "manually" remember to fix API mocks since there is no mechanism that warns us about conflicts.
Using MSW, we can already provide the generated schemas and have conflicts if a response no longer matches a schema, but nothing warns us about outdated URL paths. Being able to reuse the generated paths definition for MSW as well would provide full safety in the application as well as our mocks.

In the spirit of this library, I have been thinking about a small wrapper around MSW's http (previously rest in MSW v1) methods that can be typed with the generated paths interface. The remaining functionality of MSW would either still be imported from msw or re-exported from openapi-msw. This is definitely up for discussion.

// This example uses the v2 API of MSW
import { HttpResponse } from 'msw';
import { http } from "openapi-msw";
import { type paths } from "./generated-api-schema";

// The provided path string would be fully typed, which is currently not possible
const handler = http.get<paths>("/api/users/{id}", async ({ params }) => {
  const id = params.id;
  const user = {/* ... */};
  return HttpResponse.json(user);
});

// Since MSW supports fuzzy matches, it should be possible to define those when no `paths` argument is provided
const fuzzyMatchHandler = http.get('/api/*', async () => {
  return HttpResponse.text('No MSW handler found for api endpoint.', { status: 404 });
});

I would love to try building such wrapper and I am eager for your feedback. Do you prefer to have it in a separate project or are you interested in including it in this workspace?

[christoph-fricke]

@drwpow Since mentioning this idea, I have worked on a solution[^1] and released it to npm. What do you think about mentioning OpenAPI-MSW somewhere in this project, so people using OpenAPI-TS can find it more easily and, in the worst case, won't accidentally implement it twice. :)

[^1] https://github.com/christoph-fricke/openapi-msw

[drwpow]

Would love to! Actually, I’d love a PR adding a section to the Examples page for MSW, linking to your project. Maybe even including a short code snippet showing example usage, too.

[christoph-fricke]

That sound awesome. Thank you for the opportunity! I will create a PR in the following days where we can iterate on.
One question: Is the linked example page in the OpenAPI-Fetch documentation really the right place. OpenAPI-MSW is only using types generated by OpenAPI-TS and does not really relate to OpenAPI-Fetch (apart from both consuming the paths). Wouldn't a section somewhere in OpenAPI-TS be more relevant?

[drwpow]

Oh I see; I just misunderstood from your original post. Yes probably adding a section to advanced.md then which is currently just random sections. I’ll probably do a cleanup of that page in the future and possibly have an Examples page for openapi-typescript, but it can go there until then.

[radist2s]

@christoph-fricke, I work on Tanstack Query wrapper library to generate fully typed hooks for React. Previously I used MSW with my simple type helpers. I am glad to see such a helping library as openapi-msw. I gonna refactor my tests with your library.