Your Collections Just Became Portable

If you’ve built up a serious collection in Hoppscotch — dozens of requests, organized into folders, with auth configured and saved responses documenting what each endpoint returns — you’ve effectively written an API specification. Except you can’t use it as one. Hoppscotch has long been able to import OpenAPI specs, but the door only swung one way: once your requests lived in a collection, there was no way to get them back out as a spec. Want to generate documentation, spin up a mock server, feed a client-code generator, or hand your API surface to a teammate who uses different tooling? You’d be rewriting everything by hand in an OpenAPI editor, duplicating work you’d already done.

I built a feature for Hoppscotch that closes this loop. You can now right-click any collection and export it as a valid OpenAPI 3.1 document, in JSON or YAML. Folders, requests, parameters, bodies, auth, saved responses — the whole structure converts in one click.

What It Does

The collection context menu now has an Export as OpenAPI option. Selecting it opens a format chooser — OpenAPI 3.1 as JSON or as YAML — and the converter walks your entire collection tree recursively, turning it into a single spec document that opens cleanly in Swagger UI, Redoc, or any other OpenAPI 3.1 tool.

graph LR
A["Collection Tree"] --> B["Recursive
Conversion"]
B --> C["Paths, Tags &
Security Schemes"]
C --> D["OpenAPI 3.1
JSON / YAML"]

The mapping covers a lot of ground. Requests become path operations, with path parameters detected from the URL and servers extracted automatically. Query parameters and headers become operation parameters, with your actual values preserved as examples. Request bodies convert across content types — JSON, form-data, form-urlencoded, XML, and binary. Saved responses become OpenAPI response objects keyed by status code, so the examples you’ve captured while testing turn into real documentation. Folder hierarchy maps to slash-delimited tags, which means importers that understand tags can reconstruct your folder structure on the way back in.

Auth coverage is comprehensive: Basic, Bearer, API Key, OAuth2 across all four grant types, JWT, Digest, AWS Signature, HAWK, and Akamai EdgeGrid all map to OpenAPI security schemes. Auth and headers set at the collection level are inherited correctly — collection-level auth becomes global securitySchemes, and collection-level headers appear on each operation. Identical schemes across requests get merged, and OAuth2 scopes are unioned, so the output stays clean rather than accumulating one scheme per request. It works on both personal and team collections.

OpenAPI has one structural rule that collections don’t: a path-plus-method combination can only appear once. Your collection might legitimately have three variants of POST /users — different payloads, different scenarios. Most converters silently drop the duplicates and you discover the loss later, or never. This exporter keeps the first occurrence in the spec and preserves the rest under an x-hoppscotch-dropped-requests extension, so nothing vanishes without a trace. The same philosophy shows up in operationId generation, where collisions are deduplicated deterministically, and in malformed-URL handling, where a request that can’t parse cleanly degrades gracefully instead of aborting the whole export.

Keeping Secrets Out of Your Specs

A spec is meant to be shared, and that’s exactly why exporting one is dangerous. Your collection is full of live credentials — OAuth2 access tokens, client secrets, API keys resolved from environment variables. A naive exporter would copy them straight into a file destined for a git repo or a docs site.

This one doesn’t. OAuth2 tokens, refresh tokens, and secret request parameters are stripped during conversion — the security scheme is exported, the credentials are not. Environment variable substitution is secret-aware: non-secret variables referenced as <<var>> resolve into example values so your spec is concrete and useful, but any variable flagged as secret is never substituted, no matter which environment layer it comes from. If a secret appears anywhere in a value, the example is omitted entirely rather than risk a partial leak.

The export is also honest about what OpenAPI can’t represent. Pre-request and test scripts have no equivalent in the spec format, so they’re dropped — and the format chooser tells you so upfront, before you export, with a summary of exactly what gets left behind: scripts, auth credentials, inactive parameters, duplicate paths, and duplicate response status codes. No silent data loss, no surprise the next time you import.

Getting Started

1. Right-click a collection (or open its options menu)
2. Choose Export as OpenAPI
3. Pick your format — OpenAPI 3.1 JSON or YAML
4. Save the file and point your favorite OpenAPI tooling at it

The exported document validates as OpenAPI 3.1, so it drops straight into documentation generators, mock servers, contract-testing tools, and code generators. And because Hoppscotch already imports OpenAPI, round-tripping works too — export a collection, share the spec, and a teammate can import it back into their own workspace.

This feature is available now. You can find the full implementation in PR #5880 and try it out at Hoppscotch. It’s purely additive — the existing Hoppscotch-format export is unchanged, and nothing about your collections needs to be modified to use it.