openapi-msw v0.4.0
A tiny, type-safe wrapper around MSW to add support for full type inference from OpenAPI schema definitions that are generated with OpenAPI-TS.
Installation
You can install OpenAPI-MSW with this shell command:
npm i -D openapi-msw
Note: This package has a peer-dependency to MSW v2. There is no plan to provide backwards compatibility for MSW v1.
Usage Guide
This guide assumes that you already have OpenAPI-TS set up and configured to
generate paths
definitions. If you have not set it up, please refer to the
OpenAPI-TS setup guide before
continuing with this usage guide.
Getting Started
Once you have your OpenAPI schema types ready-to-go, you can use OpenAPI-MSW to
create an enhanced version of MSW's http
object. The enhanced version is
designed to be almost identical to MSW in usage. To go beyond MSW's typing
capabilities, OpenAPI-MSW provides optional helpers for an even better type-safe
experience. Using the http
object created with OpenAPI-MSW enables multiple
type-safety and editor suggestion benefits:
- Paths: Only accepts paths that are available for the current HTTP method
- Params: Automatically typed with path parameters in the current path
- Query Params: Automatically typed with the query parameters schema of the current path
- Request Body: Automatically typed with the request-body schema of the current path
- Response: Automatically forced to match the response-body schema of the current path
import { HttpResponse } from "msw";
import { createOpenApiHttp } from "openapi-msw";
// 1. Import the paths from your OpenAPI schema definitions
import type { paths } from "./your-openapi-schema";
// 2. Provide your paths definition to enable the above benefits during usage
const http = createOpenApiHttp<paths>();
// TS only suggests available GET paths
const getHandler = http.get("/resource/{id}", ({ params }) => {
const id = params.id;
return HttpResponse.json({ id /* ... more response data */ });
});
// TS only suggests available POST paths
const postHandler = http.post("/resource", async ({ request, query }) => {
// TS infers available query parameters from the OpenAPI schema
const sortDir = query.get("sort");
const data = await request.json();
return HttpResponse.json({ ...data /* ... more response data */ });
});
// TS shows an error when "/unknown" is not defined in the OpenAPI schema paths
const otherHandler = http.get("/unknown", () => {
return new HttpResponse();
});
Provide a Base URL for Paths
You can provide an optional base URL to createOpenApiHttp
, which is prepended
to all paths. This is especially useful when your application calls your API on
a subpath or another domain. The value can be any string that is resolvable by
MSW.
const http = createOpenApiHttp<paths>({ baseUrl: "/api/rest" });
// Requests will be matched by MSW against "/api/rest/resource"
export const getHandler = http.get("/resource", () => {
return HttpResponse.json(/* ... */);
});
Handling Unknown Paths
MSW handlers can be very flexible with the ability to define wildcards (*) in a
path. This can be very useful for catch-all handlers but clashes with your
OpenAPI spec, since it probably is not an endpoint of your API. To define
handlers that are unknown to your OpenAPI spec, you can access the original
http
object through http.untyped
.
const http = createOpenApiHttp<paths>();
// Fallback to MSW's original implementation and typings
const catchAll = http.untyped.all("/resource/*", ({ params }) => {
return HttpResponse.json(/* ... */);
});
Alternatively, you can import the original http
object from MSW and use that
one for unknown paths instead.
Optional Helpers
For an even better type-safe experience, OpenAPI-MSW provides optional helpers
that are attached to MSW's resolver-info argument. Currently, the helper query
is provided for type-safe access to query parameters.
query
Helper
Type-safe wrapper around
URLSearchParams
that implements methods for reading query parameters. For the following example,
imagine an OpenAPI specification that defines some query parameters:
- filter: required string
- sort: optional string enum of "desc" and "asc"
- sortBy: optional array of strings
const http = createOpenApiHttp<paths>();
const handler = http.get("/query-example", ({ query }) => {
const filter = query.get("filter"); // string
const sort = query.get("sort"); // "asc" | "desc" | null
const sortBy = query.getAll("sortBy"); // string[]
// Supported methods from URLSearchParams: get(), getAll(), has(), size
if (query.has("sort", "asc")) {
/* ... */
}
return HttpResponse.json({
/* ... */
});
});
License
This package is published under the MIT license.