DEV Community: Parth V Square

Chrome DevTools MCP in Claude Code (setup, attach mode, vs Playwright MCP)

Parth V Square — Sun, 25 Oct 2026 08:55:21 +0000

TL;DR: Chrome DevTools MCP is the Chrome DevTools team's open-source MCP server. It lets Claude Code, Cursor, Codex or Gemini CLI drive a real Chrome and use DevTools features: network requests, console, screenshots, performance traces, Lighthouse and heap snapshots. Install it with claude mcp add chrome-devtools --scope user -- npx chrome-devtools-mcp@latest. Add --autoConnect (Chrome 144+) to let it attach to the Chrome you're already signed in to. It's great for debugging the page in front of it. It's a poor fit for "map this app's whole API".

Why I wanted it

My agent kept writing frontend fixes it couldn't check. With a browser MCP server it opens the page, reads the console, looks at the failing request and tells me what broke. The Chrome team shipped this as a public preview in September 2025, and it now has around 60 tools (some behind opt-in flags).

Setup

You need Node.js LTS and current stable Chrome.

Claude Code

claude mcp add chrome-devtools --scope user -- npx chrome-devtools-mcp@latest

Or the plugin, which also installs skills for a11y, cookies, LCP and memory leaks:

/plugin marketplace add ChromeDevTools/chrome-devtools-mcp
/plugin install chrome-devtools-mcp@chrome-devtools-plugins

Cursor (Settings → MCP → New MCP Server) and most other clients:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Codex / Gemini CLI

codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
gemini mcp add chrome-devtools npx chrome-devtools-mcp@latest

First prompt to try: Check the performance of https://developer.chrome.com. You'll see a Chrome window open and a trace get recorded.

The network tools

There are two:

list_network_requests: requests for a page since the last navigation. Filter by resourceTypes, paginate with pageSize/pageIdx, and set includePreservedRequests to reach back 3 navigations.
get_network_request: one request with headers (including Cookie and Set-Cookie) and bodies. responseFilePath writes a big body to disk instead of into the context window.

The trick I like most: call get_network_request with no reqid and it returns whatever request you have selected in the DevTools Network panel. I click the broken call, then type "why did this 403?".

If headers carry tokens you'd rather not send to a model, start the server with --redactNetworkHeaders.

Attach mode (your signed-in browser)

By default the server launches Chrome with its own profile in ~/.cache/chrome-devtools-mcp/chrome-profile. --isolated uses a throwaway profile instead. To debug something behind your real login:

Open chrome://inspect/#remote-debugging in Chrome 144+ and allow incoming connections.
Add the flag:

   "args": ["-y", "chrome-devtools-mcp@latest", "--autoConnect"]

Approve the permission dialog Chrome shows each time the server connects. A "Chrome is being controlled by automated test software" banner stays up while it's attached.

No --autoConnect (sandboxes, older Chrome)? Start Chrome yourself and point the server at it:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable

"args": ["chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222"]

Heads up: attach mode gives the agent your cookies and signed-in accounts. Google's own docs say to only use it with agents you trust. Also, usage statistics are on by default (--no-usage-statistics), and performance tools can send trace URLs to CrUX (--no-performance-crux).

Chrome DevTools MCP vs Playwright MCP

Playwright MCP (claude mcp add playwright npx @playwright/mcp@latest) overlaps a lot. How I pick:

	Chrome DevTools MCP	Playwright MCP
Browsers	Chrome, Chrome for Testing	Chrome, Firefox, WebKit, Edge
Page model	screenshots + text snapshot	accessibility tree, no vision needed
Perf insights / Lighthouse / heap	yes	Playwright traces via `--caps=devtools`, no Lighthouse or heap tools listed
Network	list + get (headers, bodies)	list (URL regex) + get, mocking via `--caps=network`
Existing browser	`--autoConnect`, `--browser-url`	`--extension`, `--cdp-endpoint`

User flows and cross-browser checks: Playwright. "Why is this page slow or erroring in Chrome": DevTools MCP. Playwright's README also notes that coding agents may get on better with its CLI + skills, since those calls cost fewer tokens than MCP.

Where it stops for API work

Both servers only see what the browser loads while the agent is connected. When I want the agent to understand the whole API of an app, that hurts:

The request list resets per navigation (3 back at most), so the agent has to click through every screen.
Each screen costs tool calls and context.
/orders/1042 and /orders/1043 come back as separate URLs, so the agent has to figure out they're one endpoint.
Real logged-in traffic means attach mode and handing over my session.
Close the browser and the traffic is gone.

For that job I use Netraptor, a Chrome extension I work on. It records the app's fetch/XHR calls while I browse normally (or crawls same-site pages), groups them into endpoints like /orders/{id}, and its Pro plan has a local, read-only MCP server so the agent can ask "what does GET /orders/{id} return?" from real recorded responses. It has its own gap: it records from inside the page, so browser-added headers like Cookie aren't in its copy. DevTools MCP shows those. So I run both: Netraptor for "what does the API look like", DevTools MCP for "go reproduce this".

The full guide, with links to every doc above, is at netraptor.dev/guides/chrome-devtools-mcp.

Chrome won't let you paste into the console? Type "allow pasting" (no quotes)

Parth V Square — Sun, 25 Oct 2026 08:55:06 +0000

TL;DR: Paste once so the warning shows up. Then type allow pasting in the Console prompt, without quotes, and press Enter. Paste again. Chrome remembers the choice for that profile.

I set up a fresh Chrome profile last week, pasted a snippet into the Console, and got this instead of my code:

Warning: Don't paste code into the DevTools Console that you don't understand or haven't reviewed yourself. This could allow attackers to steal your identity or take control of your computer. Type "allow pasting" below and press Enter to allow pasting.

If you landed here from Google with that exact text in the search box, here is the short version and the parts that trip people up.

The fix

Open the Console (Ctrl+Shift+J, or Cmd+Option+J on a Mac).
Paste your code. Chrome blocks it and logs the warning.
Type allow pasting and press Enter.
Paste again. It lands in the prompt this time.

In the Sources panel (for example a snippet under Sources > Snippets) you get a dialog with a text field instead of a Console message. Type the same phrase there and confirm.

Why "allow pasting" sometimes doesn't work

I looked at the DevTools source to see what it checks. It compares the prompt text against the phrase exactly, and only while the warning is active. So:

Paste first. Typing the phrase before the warning appears does nothing.
No double quotes. The warning shows the phrase in double quotes, but "allow pasting" is just a JS string. The Console echoes it and you are still blocked. Plain allow pasting works, and so does 'allow pasting' with single quotes.
No extra spaces or capitals. Watch for autocomplete adding things.
Non-English DevTools uses a translated phrase. Type the one in your warning.

Why you don't see it on your main profile

Chrome only shows the warning to profiles that look new to DevTools. If your Console history has at least 5 entries, it skips the warning entirely. The Chrome team wrote this up in How Chrome DevTools helps to defend against self-XSS attacks.

It comes back when the stored setting is gone:

a new Chrome profile or a fresh install
Settings > Preferences > Restore defaults and reload
a rare bug mentioned in the Chrome post, where a new profile is the suggested fix

For CI and automation, launch Chrome with:

--unsafely-disable-devtools-self-xss-warnings

Chrome for Testing already has the warnings off. Edge is Chromium, so it behaves the same and takes the same flag.

The reason it exists: self-XSS

Self-XSS is the "paste this in your console to get free credits" scam. Whatever you paste runs as you on that site. It can:

read localStorage, sessionStorage and any cookie that isn't HttpOnly, which is where a lot of apps keep tokens
call the site's API with your session
fetch all of it off to someone else's server

For us the phrase is a one-time speed bump. The habit worth keeping is reading every paste before you hit Enter.

Safer habits for code you copied

Use a Snippet for anything you run twice. Sources > Snippets > New snippet, paste, save, then Ctrl+Enter / Cmd+Enter. You can also run it from the Command Menu (Ctrl+Shift+P, delete the >, type !snippet-name).

Read a copied fetch before running it. Check that:

the URL is the host you expect
the method is what you want (POST and DELETE change data)
the body is readable JSON or form data
nothing extra wraps the call, like eval, atob, or a second fetch that ships document.cookie somewhere

Prefer cURL in a terminal if you only need the response. It runs outside the page, so it can't touch page storage. It still carries your cookies and auth headers, so don't drop it into Slack.

Skipping the paste entirely

Half the time I'm pasting because I copied a request as fetch and want to replay it with a tweak. I use Netraptor for that now (disclosure: it's ours). It's a DevTools panel where you right-click a request and pick Resend, or Edit and resend as fetch to change the method, URL, headers or body first. It runs the request with fetch inside the inspected page using the page's cookies, and the result shows up tagged Resent. The same menu copies as cURL (bash/cmd), PowerShell, fetch or Node.js fetch. It only works on live traffic, since it needs the page you're inspecting.

Full guide, with the Sources dialog and FAQ: Allow pasting in the Chrome console

How to create a HAR file in Chrome without leaking your tokens

Parth V Square — Sun, 25 Oct 2026 08:54:55 +0000

TL;DR: Open DevTools > Network, check Preserve log and Disable cache, clear, reload, reproduce the bug, then click Export HAR (sanitized).... Since Chrome 130 that export drops Cookie, Set-Cookie and Authorization. Tokens in URLs, custom headers like X-Api-Key, and request and response bodies are still in the file. Run a grep over it before you attach it to a ticket.

Every support team eventually asks for "a HAR file". Most of the bad ones I've seen came from the same three mistakes: DevTools opened too late, Preserve log off, or a filter left on. Here's the version that works on the first try.

The steps

Go to the page with the problem and open DevTools (F12, Ctrl+Shift+I, or Cmd+Option+I on macOS). Click Network. Do this before you reproduce anything, because Chrome only logs requests while DevTools is open.
Check Preserve log (so redirects and logins don't wipe the list) and Disable cache (so you see what a first-time visitor sees).
Click the clear button, then reload. Now the log starts from a clean page load.
Reproduce the bug. Keep DevTools open until it has happened.
Clear the Filter box and select All. A leftover Fetch/XHR chip is an easy way to ship half a file.
Click the download icon, Export HAR (sanitized)..., and save. Right-clicking any request gives you Save all as HAR (sanitized) too.

If the flow opens a popup or a new tab (hello, SSO), those requests land in that tab's DevTools. Turn on Auto-open DevTools for popups in DevTools settings first.

"Sanitized" covers three headers

Chrome 130 changed the default export (release notes). The sanitized file leaves out:

Cookie
Set-Cookie
Authorization

That's the whole list. If you actually need those headers, say to debug your own auth flow, go to DevTools Settings > Preferences > Network, check Allow to generate HAR with sensitive data, then long-click the Export button and pick Export HAR (with sensitive data).

Edge behaves the same since it's the same DevTools. Firefox (Network Monitor gear menu > Persist Logs, then Save All As HAR) and Safari (Web Inspector > Network > Preserve Log, then Export) put cookies and auth headers in the file along with everything else.

What's still in a sanitized HAR

Things I've found in "sanitized" HAR files:

X-Api-Key, X-CSRF-Token, X-Auth-Token headers
?access_token=... and ?api_key=... in URLs, including inside Referer and Location
OAuth ?code= values on the login redirect
The password in a login request body, in plain text
Refresh tokens in token-exchange calls and fresh access tokens in login responses
Names, emails and addresses in ordinary API responses

Scrubbing it

First, record less. Log in, clear the log, then reproduce only the failing steps.

Then strip the headers you know about. With jq:

jq '.log.entries[] |= (
  .request.headers |= map(select(.name | test("^(cookie|authorization|x-api-key)$"; "i") | not))
  | .response.headers |= map(select(.name | test("^set-cookie$"; "i") | not))
  | .request.cookies = []
  | .response.cookies = []
)' session.har > session.scrubbed.har

Headers are the easy part. Now look for everything else:

grep -n -i -E 'token|secret|password|api[_-]?key|bearer|eyJ' session.scrubbed.har

eyJ catches JWTs, because {" base64-encodes to eyJ. Every hit is a value to replace by hand or a step to leave out of the recording. Google's HAR Analyzer can also download a redacted copy. Whatever you couldn't remove, log out or rotate the key once the ticket is closed.

A sanitizer that also reads URLs and bodies

I work on Netraptor, a Chrome extension that adds its own Network panel to DevTools, and its Save all as HAR (sanitized) goes further than Chrome's. It drops any header with a credential-like name (token, secret, password, session, auth, csrf, jwt, key, and so on), sets matching query and fragment params plus OAuth code to [redacted], redacts matching keys at any depth in JSON and form bodies, and removes bodies it can't parse (HTML, text, binary) with a comment saying so. It saves only the rows you have filtered to, so you can export just the failing calls. It matches on field names, so an email under email or a token in a URL path still gets through. Run the grep anyway.

The full guide, with FAQ and a section on why HAR files come out empty, is here: How to create a HAR file in Chrome.

Chrome's Network tab keeps clearing on reload. Here's how to stop it

Parth V Square — Sun, 25 Oct 2026 08:54:33 +0000

TL;DR: In Chrome DevTools, open the Network panel and tick Preserve log. Requests then survive reloads and redirects. They still vanish when you close DevTools, anything before DevTools opened is missing, and every page load lands in one unlabelled list. In Firefox the option is Persist Logs, under the gear icon in the Network Monitor.

The problem

You're debugging a login. The form posts, the server redirects, and the request you needed is gone. Chrome's Network panel clears its list every time the main frame loads a new document. That covers reloads, links, form posts and server redirects.

Turn on Preserve log

Open DevTools before loading the page (F12, or Cmd+Option+I on macOS). Chrome only records requests while DevTools is open.
Click the Network tab.
Tick Preserve log in the action bar at the top.
Reproduce the reload or redirect. The old requests stay put and new ones are added below them.
Before you close DevTools, export a HAR (download icon in the action bar) if you want to keep any of it.

The Console has its own Preserve log in its settings. Turn that on too if you want console messages to survive the reload.

Where it falls short

I hit these regularly:

Closing DevTools wipes it. The preserved log lives in the DevTools window. Close it and the log is gone.
The first load is often missing. If the page loaded before you opened DevTools, those requests were never recorded. Reload with DevTools open. For popups, start Chrome with:

  google-chrome --auto-open-devtools-for-tabs

If you need a capture that doesn't depend on DevTools at all, chrome://net-export writes a browser-level NetLog.

One flat list. After five reloads you have five copies of /api/me and nothing telling you which load each one belongs to. You end up reading the order of the document requests and the waterfall.
SPAs never clear anyway. A history.pushState route change isn't a document load, so the log never clears. With or without Preserve log, every route's API calls pile into the same list with no marker between them.

Disable cache is a different job

Disable cache sits right next to it. Preserve log decides whether the list survives a reload. Disable cache decides whether the requests in it hit the network or come from the HTTP cache (only while DevTools is open). If a request seems missing after a reload, check whether it came from the memory or disk cache before you assume it never ran.

Firefox: Persist Logs

Open the Network Monitor (Ctrl+Shift+E, or Cmd+Option+E on macOS).
Click the gear icon at the right end of the Network toolbar.
Select Persist Logs.

The Web Console has its own Persist Logs setting too. The limits are the same as Chrome's.

What I use when the flat list gets in the way

I work on Netraptor, a Chrome extension with its own DevTools panel, and this was one of the gaps we wanted to close. When you open the panel it pulls in what DevTools already logged for the page. After that, each reload, navigation or SPA route change (pushState, replaceState, back/forward) starts a group labelled "Reloaded" or "Navigated to" with the path, time and request count. Earlier loads fold away rather than being deleted. If you turn on "Keep history for this site", it saves that site's fetch/XHR calls to IndexedDB, so they're still there after you close DevTools.

The full guide, with steps and FAQ, is here: Preserve log in Chrome: keep network requests after a page reload.

What is a HAR file, and how to get one from Chrome

Parth V Square — Fri, 23 Oct 2026 19:04:44 +0000

A HAR file (HTTP Archive) is a JSON file that records every network request a browser made while a page was open, including URLs, headers, request bodies, responses and timings. Support teams ask for one because it shows exactly what your browser sent and received when something broke. You can generate a HAR file in Chrome from the Network panel in DevTools in under a minute.

Disclosure: I build Netraptor, which this guide mentions as one option. The steps work with plain Chrome and free tools.

Steps

Open the Network panel. Go to the page with the problem and open DevTools with F12, Ctrl+Shift+I on Windows and Linux, or Cmd+Option+I on macOS. Click the Network tab.
Turn on Preserve log. Check Preserve log so requests are kept across page loads and redirects. Check Disable cache too if the problem only shows up on a fresh load.
Reproduce the problem. Reload the page and repeat the exact steps that cause the issue. DevTools only records while it is open, so keep it open the whole time.
Export the HAR file. Click the download icon, Export HAR (sanitized)..., in the action bar at the top of the Network panel, and choose where to save the file.
Check the file before sharing. Open the .har file in a text editor and search for tokens, emails or other secrets before you send it to anyone.

What is a HAR file?

HAR stands for HTTP Archive. A HAR file is plain JSON with a .har extension that describes a browser's network activity: one entry per request, grouped under the pages that triggered them. Chrome, Edge, Firefox and Safari can all export it, and most debugging tools can read it.

The format was drafted as HAR 1.2 for the W3C Web Performance Working Group. That draft was never published as a standard and is now marked as abandoned, but browsers still write files that follow it. A trimmed HAR file looks like this:

{
  "log": {
    "version": "1.2",
    "creator": { "name": "WebInspector", "version": "537.36" },
    "pages": [{ "id": "page_1", "title": "https://app.example.com/" }],
    "entries": [
      {
        "pageref": "page_1",
        "startedDateTime": "2026-10-16T09:12:03.120Z",
        "time": 184.2,
        "request": { "method": "GET", "url": "https://app.example.com/api/orders" },
        "response": { "status": 500, "statusText": "Internal Server Error" },
        "timings": { "blocked": 1.1, "dns": 0, "connect": 0, "send": 0.2, "wait": 176.4, "receive": 6.5 }
      }
    ]
  }
}

What's inside a HAR file

Each entry in log.entries captures one request and its response. The fields you will look at most:

request: method, full URL, query string, headers, cookies and the request body (postData).
response: status code, headers, cookies, MIME type and usually the response body in content.text.
timings: how long the request spent blocked, on DNS, connecting, sending, waiting for the server (wait) and downloading (receive), in milliseconds.
startedDateTime and time: when the request began and how long it took in total.
pages: the page loads the requests belong to, so you can tell which navigation triggered what.

Because it holds full headers and bodies, a HAR file is often the fastest way for someone else to see a failed API call, a slow request or a bad redirect without access to your account.

Export HAR (sanitized) vs. with sensitive data

Since Chrome 130, the default HAR export is sanitized: it leaves out the Cookie, Set-Cookie and Authorization headers. This change was made to cut down on accidental leaks of login sessions when people attach HAR files to support tickets.

If you need those headers, for example to debug your own auth flow, open DevTools Settings > Preferences > Network and turn on Allow to generate HAR with sensitive data. The Export HAR button then offers both a sanitized and a sensitive-data option. See the Network features reference for the current labels.

Sanitized only removes those three headers. Tokens in URLs, request bodies, custom headers like X-Api-Key and response bodies are still in the file.

How to get a HAR file in Edge, Firefox and Safari

Microsoft Edge uses the same DevTools as Chrome. Follow the steps above.
Firefox: open the Network Monitor (Ctrl+Shift+E or Cmd+Option+E), reproduce the issue, then right-click any request and choose Save All As HAR.
Safari: enable the Develop menu in Safari settings, open Web Inspector, go to the Network tab, reproduce the issue and click Export.

Whichever browser you use, start recording before you reproduce the problem. A HAR file only contains requests made while the network tools were open.

Is it safe to share a HAR file?

Treat a HAR file like a password. A file exported with sensitive data contains session cookies and bearer tokens, and anyone who has it can often act as you until those expire. Even a sanitized file can include personal data from API responses, IDs in URLs and API keys in custom headers.

Before you share one:

Use the sanitized export unless the recipient specifically needs auth headers.
Record in a fresh tab with only the steps needed to reproduce the issue, so unrelated traffic stays out of the file.
Search the file for token, key, password, secret and your email address.
Log out after sending a file that included cookies. That invalidates the session on most sites.

Google's HAR Analyzer also has a redaction button that downloads a copy with sensitive values removed.

Doing this with Netraptor

Chrome's Network panel records everything, but only while DevTools is open, and you have to remember to turn on Preserve log first. If you capture the same app often, Netraptor can record it in the background instead.

In the Netraptor toolbar popup, turn on Record this site. It records the fetch and XHR API traffic for that domain and its subdomains across page loads, with or without DevTools open.
Open the Netraptor panel in DevTools to browse the recorded requests in a Chrome-style Requests table, or group them by endpoint in API Map.
On the Export tab, export a HAR file. Strip auth headers and cookies is on by default, so the file is safer to share.

HAR export is part of the Free plan, along with Postman and curl exports. Everything stays in your browser and no account is needed. Netraptor records API calls only, so if you need images, scripts and the full page-load waterfall in the file, use Chrome's own export.

What to do with a HAR file next

Once you have the file, you can load it back into Chrome DevTools, open it in an online viewer or query it with jq. See how to open and analyze a HAR file. If you want to replay the requests you captured, turn them into a Postman collection.

FAQ

What does HAR stand for?

HAR stands for HTTP Archive. It is a JSON-based format for logging a browser's network requests and responses.

Why is my HAR file empty?

DevTools only records network traffic while it is open. Open the Network panel first, check Preserve log, then reload the page and reproduce the problem before exporting.

Can I open a HAR file in Notepad?

Yes. A HAR file is plain JSON text, so any text editor can open it. For a readable request list, import it into the Chrome DevTools Network panel or a HAR viewer.

Does a HAR file contain my password?

It can. If you log in while recording, the login request body may include your password in plain text. Record after logging in, or check the file before sharing it.

Why are cookies missing from my HAR file?

Chrome exports sanitized HAR files by default and strips the Cookie, Set-Cookie and Authorization headers. Turn on Allow to generate HAR with sensitive data in DevTools settings if you need them.

Originally published at netraptor.dev/guides/what-is-a-har-file. More guides: netraptor.dev/guides.

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

Parth V Square — Fri, 23 Oct 2026 19:04:12 +0000

An OpenAPI spec is a JSON or YAML document that describes an HTTP API in a standard, language-agnostic format, listing its paths, methods, parameters, request bodies and responses. If your API has no spec yet, you can generate a first draft from real traffic by recording the requests your web app makes in Chrome, exporting them as a HAR file, and converting that file with an open-source tool such as mitmproxy2swagger. You then review the draft by hand, because traffic only shows what was actually called.

Disclosure: I build Netraptor, which this guide mentions as one option. The steps work with plain Chrome and free tools.

Steps

Record the app's API calls in Chrome. Open DevTools (F12, or Cmd+Option+I on a Mac), go to the Network panel, check Preserve log, click the Fetch/XHR filter and reload the page.
Use every feature you want in the spec. Sign in with a test account and walk through each screen. Create, edit and delete test records so every endpoint and HTTP method shows up at least once.
Export a HAR file. Click Export HAR (sanitized) in the Network panel toolbar and save the file as app.har. The sanitized export leaves out Cookie, Set-Cookie and Authorization headers.
Run a first pass with mitmproxy2swagger. Install it with pip install mitmproxy2swagger, then run mitmproxy2swagger -i app.har -o openapi.yaml -p https://api.example.com. The output lists every discovered path under x-path-templates, each prefixed with ignore:.
Pick the paths and run it again. Remove the ignore: prefix from the paths you want, fix templates such as /users/{id}, and run the same command again. The second pass writes the operations into paths.
Validate and edit the result. Paste the file into Swagger Editor or run openapi-generator-cli validate -i openapi.yaml. Then add descriptions, required fields, error responses and auth by hand.

What is OpenAPI?

The OpenAPI Specification (OAS) defines a standard, programming-language-agnostic way to describe HTTP APIs. A tool or a person can read an OpenAPI document and learn which endpoints exist, what each one accepts and what it returns, without reading the server code.

OpenAPI started as the Swagger Specification. SmartBear donated it to the OpenAPI Initiative under the Linux Foundation in late 2015, and it was renamed in early 2016. Today "OpenAPI" is the name of the format, and "Swagger" usually refers to SmartBear's tools such as Swagger UI and Swagger Editor.

The published versions are 2.0, the 3.0.x line, the 3.1.x line and the 3.2.x line, with 3.2.1 the newest. Version 3.1 aligned its Schema Object with JSON Schema draft 2020-12, and most current tools read 3.0 and 3.1. If a tool you rely on rejects a newer version, check its docs before choosing.

What does an OpenAPI spec look like? (JSON and YAML)

An OpenAPI document is one JSON or YAML file, conventionally named openapi.json or openapi.yaml. It must have an openapi version field and an info object, plus at least one of paths, components or webhooks. Path parameters are written in curly braces, and every placeholder must match a parameter definition.

openapi: 3.1.0
info:
  title: Example app API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Get a user
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The user
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string }
                  email: { type: string }

The JSON form holds the same structure with braces and quotes. YAML is easier to edit by hand, JSON is easier to generate and parse, and most tools accept either.

What a spec generated from traffic will miss

Recorded traffic shows real requests and responses, which makes it a good starting point. It also has gaps you need to fill before anyone treats the file as documentation.

Endpoints you never triggered are missing. Admin screens, error paths and rarely used features only appear if you exercise them.
Schemas are inferred from examples. A field that was null in every response, or an optional field you never sent, will be typed loosely or left out.
Path parameters need checking. Generators guess which segments are IDs, so /users/42 and /users/me can end up merged or split the wrong way.
Auth is usually missing. Add a securitySchemes entry under components (for example a bearer token) and a security requirement yourself.
Enums, formats, limits and descriptions come from you, not the traffic.

Treat the generated file as a draft. One careful review pass usually turns it into something your team can rely on.

Is it safe to generate a spec from production traffic?

Be careful with what goes into the HAR file and the spec. Chrome's sanitized HAR export removes Cookie, Set-Cookie and Authorization headers, but request and response bodies stay in the file, and so do tokens passed in URLs or custom headers.

mitmproxy2swagger adds example data only when you pass --examples (and headers with --headers). Its README warns that this can include sensitive data. If you want examples in the spec, record against a test account with fake data, then read the examples before you commit or share the file.

Record traffic only from apps you build, test or are authorised to test, and prefer a staging environment over production.

What to do with an OpenAPI spec once you have one

Publish docs. Swagger UI and similar tools render the file as browsable reference pages.
Generate clients and server stubs. OpenAPI Generator takes -i (the spec), -g (a generator such as typescript-fetch) and -o (an output folder).
Test against it. The spec becomes a contract you can check the real API against in CI.
Import it into Postman. Postman imports OpenAPI 3.0 and 3.1 as a collection. See Create a Postman collection from a website's requests.

If you only need the list of endpoints and not a full spec, Find every API endpoint your web app calls covers the DevTools side in more detail.

Faster: generate the spec with Netraptor

Netraptor is a Chrome extension with its own DevTools panel. It shortens the record, convert and template steps above, and everything stays local in your browser.

Turn on "Record this site" in the toolbar popup. Netraptor records fetch/XHR API traffic for that domain and its subdomains across page loads, even with DevTools closed.
Optionally run "Crawl this site" to visit same-origin links in your logged-in tab. It skips logout and delete-looking links. Free crawls cover 25 pages, Pro up to 1000.
Check the API Map tab. Endpoints are grouped and IDs are already parameterized, for example /users/{id}.
In the Export tab, export OpenAPI 3.1 as YAML or JSON, with optional response samples. "Strip auth headers and cookies" is on by default.

OpenAPI export is part of Pro ($29.99 one-time, no subscription). The Free plan exports HAR, Postman Collection v2.1 and curl, so you can export a HAR from Netraptor and run it through mitmproxy2swagger instead. You still review the generated spec by hand either way.

FAQ

Is OpenAPI the same as Swagger?

OpenAPI is the specification, and it was called the Swagger Specification until 2016. Swagger now refers to SmartBear's tools, such as Swagger UI and Swagger Editor, that work with OpenAPI files.

Should I use OpenAPI 3.0, 3.1 or 3.2?

Use 3.1 unless a tool in your pipeline only supports 3.0. Version 3.1 matches JSON Schema 2020-12, and 3.2 is newer, so check tool support before adopting it.

What is OpenAPI Generator?

OpenAPI Generator is an open-source CLI that turns an OpenAPI document into client SDKs, server stubs and docs for many languages. It also has a validate command for checking a spec.

Can I generate an OpenAPI spec from code instead of traffic?

Yes, if you own the backend. Many frameworks, FastAPI for example, produce a spec from route definitions, and that is usually more complete than one inferred from traffic.

What is the difference between openapi.json and openapi.yaml?

They hold the same document in two syntaxes. The spec allows both, and most tools accept either.

Originally published at netraptor.dev/guides/generate-openapi-spec-from-traffic. More guides: netraptor.dev/guides.