openapi-msw

OpenAPI-MSW

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. 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
• 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 getHandler = http.post("/resource", async ({ request }) => {
  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.

License

This package is published under the MIT license.

Changelog

0.1.2

Patch Changes

• #17 2931f0c Thanks @christoph-fricke! - Fixed OpenAPI operations with no-content responses cannot return a response. Now they are required to return an empty response, i.e. null as response body.

  const http = createOpenApiHttp<paths>();
  
  // Resolver function is required to return a `StrictResponse<null>` (empty response)
  // if the OpenAPI operation specifies `content?: never` for the response.
  const noContent = http.delete("/resource", ({ params }) => {
    return HttpResponse.json(null, { status: 204 });
  });