OpenAPI: Browser support without polyfills

tjosepo commented 2 months ago

Description

The function fromOpenApi currently doesn't work on the browser without a lot of Node.js polyfills.

The file open-api-utils.ts uses status codes from node:http.
The transitive dependency @apidevtools/swagger-parser > @apidevtools/json-schema-ref-parser uses the path, fs, http and https modules. It also references process.cwd.

Solution

For open-api-utils.ts, inlining the STATUS_CODE variable is easy enough.

For @apidevtools/json-schema-ref-parser, since it is the ubiquitous library used for JSON Schema dereferencing in Node, it may not make sense to replace it in Node. We could create a separate package entrypoint for the browser that prebundles the Node.js modules or replaces the library with web-compatible alternative (that may not support all features of JSON Schema dereferencing, but works for the web.)

Alternatives

Ask consumers of the library to bring their own polyfills. Will hurt the ability of teams to adopt this library. (I haven't been able to fully polyfill everything with Webpack, so I don't even know if it's possible.)
Make @mswjs/source/open-api a Node.js only feature.
Raise this issue to the @apidevtools folks. Make the change there.

weyert commented 2 months ago

Yeah, I think that's a good idea. I am wondering if we could leverage a package like @stoplight/http-spec. They also have a fork of @apidevtools/json-schema-ref-parser which appears to work in the browser but I am not sure if they use poly fills for it (probably?).

I think we might able to use this http-spec as for some cli-tool to generate HttpHandler stubs from a Postman collection file :)

kettanaito commented 2 months ago

Thanks for opening this, @tjosepo. I would love to see Source working in the browser for OpenAPI. Our best approach here is to find packages that can provide us with parsing while not relying on Node.js native modules.

@weyert, http-spec looks interesting. Do you have some usage examples of how it parses the OAS documents? I'd love to see those.

VobileLiuZhiwu commented 1 month ago

@kettanaito @tjosepo @weyert I believe a better solution would be to provide an initialization command that generates the JSON string for the specification needed by const specification = await SwaggerParser.dereference(document), which can then be passed as an argument to fromOpenApi. What do you think?

tjosepo commented 1 month ago

@VobileLiuZhiwu OpenAPI specifications can have circular references, but JSON strings do not support circular references. Because of this, I don't think this approach is suitable. :/

kettanaito commented 3 weeks ago

I love the approach @tjosepo has chosen in #51. The changes will be automatically published tomorrow.

kettanaito commented 3 weeks ago

Released: v0.3.0 🎉

This has been released in v0.3.0!

📄 Release notes
📦 npm package

Make sure to always update to the latest version (npm i @mswjs/source@latest) to get the newest features and bug fixes.

Predictable release automation by @ossjs/release.

mswjs / source