Demystify

Generate OpenAPI Specifications in Real Time for Any API
Understand API Behaviour »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
2. Getting Started
   • Desktop App
     • Mac
     • Linux
     • Windows
   • Browser Extension
     • Chrome
     • Firefox
   • CLI
   • Library
3. Screenshots
4. Contributing
5. License

About The Project

demo.mp4

Demystify is a suite of tools designed to help understand API behaviour. It generates accurate OpenAPI 3.1 specifications in real time from live network traffic or HAR files. The desktop app achieves this with a built-in proxy, while the browser extension works automatically for all requests in a given tab. The CLI tool works directly on files, and the library can be used in other contexts such as middleware to programmatically generate API specifications.

It identifies path parameters automatically without manual intervention. Data in the generated specification reflects all observed information across multiple status codes and mime types for request and response headers, bodies, query parameters, path parameters, and cookies for each endpoint.

(back to top)

Getting Started

Demystify is available in a variety of formats on various platforms.

Desktop

The desktop app has a built in proxy that captures network traffic and generates OpenAPI specifications in real time. It is designed to be simple and quick to use, and specifies a local port to listen to and a local or remote host to forward to.

Mac

Linux

Windows

Browser Extension

The browser extension can be accessed in the DevTools of your chosen browser. While the tool is open it will record all network requests in the same tab and generate OpenAPI specifications in real time from network traffic.

Chrome

I have submitted this to Chrome Web Store and am awaiting approval. After that the link will be updated.

Locate the tool in Chrome DevTools.

Firefox

Locate the tool in Firefox DevTools.

CLI

npx demystify --input <somefile.har>

Usage: demystify [options]

Example: demystify --input ./example.har

Options:
  -h, --help                 Show help information
  -i, --input  <string>      A path to a HTTP Archive file (HAR)
  -s, --stdout <boolean>     Optional: when "true", write a JSON array to stdout instead of writing files

This command writes OpenAPI 3.1 specifications to the current directory
Names of these files follow the convention {host}.{type}.json

Example host: api.example.com
Example type: openapi

Library

npm install demystify-lib

import { Representor } from "demystify-lib";
// Instantiate the representor
// Which "represents" an API in a particular way, such as OpenAPI or GraphQL
const representor = new Representor();
// Call upsert with a valid HAR entry to add it to the representor
// Repeat as many times as desired
representor.upsert(/* harEntry */);
// Call generate on the rest property of representor to generate OpenAPI documents
const doc = representor.rest.generate();

See test files for more information on usage.

(back to top)

Screenshots

Watch live network traffic or a HAR file become API specifications
that update in real time in response to new requests

The browser extension can use Scalar's built in API client
with prepopulated fields froms recent values

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

1. Fork the Project
2. Install and build npm i && npm run build
3. Create your Feature Branch (git checkout -b feature/AmazingFeature)
4. Commit your Changes (git commit -m 'Add some AmazingFeature')
5. Test your changes, e.g. by loading the browser extension from apps/browser/.output/chrome-mv3/
6. Push to the Branch (git push origin feature/AmazingFeature)
7. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)