What is an OpenAPI spec, and how to generate one from your web app's traffic

An OpenAPI spec is a JSON or YAML document that describes an HTTP API in a standard, language-agnostic format. It lists the API's paths, methods, parameters, request bodies, and responses. If your API lacks a spec, you can generate a first draft from real traffic by recording requests in Chrome, exporting them as a HAR file, and converting that file using tools like mitmproxy2swagger. Review the draft manually, as traffic reveals only what was actually called.

To generate an OpenAPI spec from web app traffic, open Chrome's Developer Tools, navigate to the Network panel, check "Preserve log", and use the Fetch/XHR filter. Reload the page to capture all desired API calls. Create, modify, and delete test data to ensure every endpoint and HTTP method appears in the HAR file. Export the HAR file and run it through mitmproxy2swagger to create a draft spec.

Review the spec manually, removing any unwanted elements, fixing templates, and adding missing information such as descriptions, error responses, and authentication details.

OpenAPI, formerly known as the Swagger Specification, is a standard for describing HTTP APIs. It is maintained by the OpenAPI Initiative, which is part of the Linux Foundation. The latest version is 3.2.1. An OpenAPI spec is a single JSON or YAML file with an openapi version field, an info object, and either paths, components, or webhooks. Path parameters are defined in curly braces, and generators may incorrectly infer some parameters.

While traffic provides real requests and responses, it lacks certain elements typically found in a spec, such as endpoints that were never triggered, admin screens, error paths, and rarely used features. Schemas are inferred from examples, so fields with null values or optional fields may be misrepresented. Paths need careful checking, and authentication is usually missing. Add this information manually.

Be cautious when generating a spec from production traffic. Avoid including sensitive data such as cookies, set-cookies, authorization headers, request and response bodies, and tokens in the HAR file. If you need examples, use a test account with fake data. Generate an OpenAPI spec only from apps you own, test, or are authorized to test, and prefer using a staging environment over production. The resulting spec can be used to publish documentation, generate client and server stubs, and test the API against the spec in CI.