feat: implement msw plugin

Author: malcolm-kee

docs/openapi-ts/plugins/msw.md

@@ -4,15 +4,138 @@ description: MSW plugin for Hey API. Compatible with all our features.
 ---
 
 <script setup lang="ts">
-import FeatureStatus from '@components/FeatureStatus.vue';
 </script>
 
-# MSW <span data-soon>soon</span>
-
-<FeatureStatus issueNumber=1486 name="MSW" />
+# MSW
 
 ### About
 
 [MSW](https://mswjs.io) is an API mocking library that allows you to write client-agnostic mocks and reuse them across any frameworks, tools, and environments.
 
+The MSW plugin for Hey API generates type-safe mock handler factories from your OpenAPI spec, removing the tedious work of defining mock endpoints and ensuring your mocks stay in sync with your API.
+
+## Features
+
+- type-safe mock handlers generated from your OpenAPI spec
+- seamless integration with `@hey-api/openapi-ts` ecosystem
+- support for static response values or custom MSW resolver functions
+- typed path parameters and request bodies
+- automatic base URL inference from OpenAPI `servers` field
+- minimal learning curve thanks to extending the underlying technology
+
+## Installation
+
+::: warning
+MSW plugin requires `msw@^2` as a peer dependency. Make sure to install it in your project.
+:::
+
+In your [configuration](/openapi-ts/get-started), add `msw` to your plugins and you'll be ready to generate MSW artifacts. :tada:
+
+```js
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    'msw', // [!code ++]
+  ],
+};
+```
+
+## Output
+
+The MSW plugin will generate a `msw.gen.ts` file containing the following artifacts.
+
+### Handler Factory
+
+The `createMswHandlerFactory` function is the main export. It returns an object with an `of` property containing a handler creator for each operation in your spec.
+
+```ts
+import { createMswHandlerFactory } from './client/msw.gen';
+
+const createMock = createMswHandlerFactory({
+  baseUrl: 'http://localhost:8000', // optional, inferred from spec servers
+});
+```
+
+If your OpenAPI spec defines a `servers` field, the base URL will be inferred automatically. You can override it by passing `baseUrl` in the configuration.
+
+### Handler Creators
+
+Each operation becomes a handler creator on the `of` object. Handler creators accept either a static response value or a custom MSW `HttpResponseResolver` function.
+
+## Usage
+
+### Static Response
+
+The simplest way to mock an endpoint is to provide a static response value. The value is type-checked against the operation's response type.
+
+```ts
+import { setupServer } from 'msw/node';
+import { createMswHandlerFactory } from './client/msw.gen';
+
+const createMock = createMswHandlerFactory();
+
+const mockServer = setupServer(
+  // provide a static response value
+  createMock.of.getPetById({ id: 1, name: 'Fido' }),
+
+  // type error if response type is incorrect
+  // @ts-expect-error
+  createMock.of.getPetById('wrong type'),
+);
+```
+
+### Custom Resolver
+
+For more control, pass an MSW `HttpResponseResolver` function. The resolver receives typed path parameters and request body when available.
+
+```ts
+import { delay, HttpResponse } from 'msw';
+import { setupServer } from 'msw/node';
+import { createMswHandlerFactory } from './client/msw.gen';
+
+const createMock = createMswHandlerFactory();
+
+const mockServer = setupServer(
+  // custom resolver with typed params and body
+  createMock.of.updatePet(async ({ request, params }) => {
+    const body = await request.json();
+    return HttpResponse.json({ id: Number(params.petId), ...body }, { status: 200 });
+  }),
+
+  // async resolver with delay
+  createMock.of.getPetById(async () => {
+    await delay(100);
+    return HttpResponse.json({ id: 1, name: 'Fido' });
+  }),
+);
+```
+
+::: tip
+Path parameters are typed as `string | ReadonlyArray<string>` because MSW normalizes all path parameters to strings. Use `Number()` or similar conversions if you need numeric values.
+:::
+
+### Operations Without Responses
+
+For operations that don't define a response type, the handler creator accepts `undefined` or a custom resolver function.
+
+```ts
+const mockServer = setupServer(
+  createMock.of.deletePet(undefined),
+
+  createMock.of.deletePet(() => new HttpResponse(null, { status: 204 })),
+);
+```
+
+## Known Limitations
+
+- Query parameters are not typed in the resolver. MSW doesn't provide typed query params natively — use `new URL(request.url).searchParams` instead.
+- The response type generic is omitted from `HttpResponseResolver` to avoid MSW's `DefaultBodyType` constraint issues with union and void response types.
+
+## API
+
+You can view the complete list of options in the [UserConfig](https://github.com/hey-api/openapi-ts/blob/main/packages/openapi-ts/src/plugins/msw/types.ts) interface.
+
+<!--@include: ../../partials/examples.md-->
 <!--@include: ../../partials/sponsors.md-->

examples/openapi-ts-fetch/openapi-ts.config.ts

@@ -18,5 +18,6 @@ export default defineConfig({
       enums: 'javascript',
       name: '@hey-api/typescript',
     },
+    'msw',
   ],
 });

examples/openapi-ts-fetch/package.json

@@ -9,6 +9,7 @@
     "lint": "eslint . --report-unused-disable-directives --max-warnings 0",
     "openapi-ts": "openapi-ts",
     "preview": "vite preview",
+    "test": "vitest run",
     "typecheck": "tsgo --noEmit"
   },
   "dependencies": {
@@ -29,10 +30,12 @@
     "eslint": "9.17.0",
     "eslint-plugin-react-hooks": "5.2.0",
     "eslint-plugin-react-refresh": "0.4.7",
+    "msw": "2.10.2",
     "oxfmt": "0.27.0",
     "postcss": "8.4.41",
     "tailwindcss": "3.4.9",
     "typescript": "5.9.3",
-    "vite": "7.3.1"
+    "vite": "7.3.1",
+    "vitest": "4.0.18"
   }
 }