OpenAPI Detection: a beginner's guide

OpenAPI is a standard format for describing REST APIs in machine-readable form. An OpenAPI document is a YAML or JSON file that lists every endpoint of an API, the parameters each one takes, the data types of the request and response bodies, the authentication scheme, and (often) human-readable descriptions of what each operation does. The standard was originally created by Swagger, Inc. in 2010, and was renamed to OpenAPI when the project was donated to the Linux Foundation in 2015. Today, OpenAPI is the universal way that REST APIs document themselves, and almost every major API published in the last five years has an OpenAPI spec available somewhere — sometimes at a well-known path like `/openapi.json`, sometimes linked from the docs, sometimes (unfortunately) hidden in private repositories.

You should care because finding a public OpenAPI spec for an API is the fastest possible way to integrate with it. With a spec in hand, you can auto-generate client libraries in any language, import the API into Postman or Insomnia for interactive exploration, validate request and response payloads automatically, and (with some tools) generate a working backend stub for testing. Without a spec, you are stuck reading documentation by hand, copying examples, and guessing about edge cases. For an integrator, a partner, a security researcher, or a competitor doing teardowns, an OpenAPI spec is a treasure.

The five things every OpenAPI discovery check looks at:

• Well-known paths. `/openapi.json`, `/openapi.yaml`, `/swagger.json`, `/api-docs`, `/v3/api-docs` (Spring Boot), `/docs/openapi.json`.

• HTML pages that link to specs. Swagger UI, Redoc, and Stoplight all generate documentation pages that link to the underlying spec.

• Response headers. Some APIs include `Link: </openapi.json>; rel="service-desc"`.

• Robots.txt and sitemap entries. Some APIs list their docs in their public discovery files.

• Subdomains. `docs.example.com`, `api-docs.example.com`, `developer.example.com` are common locations.

Three questions an OpenAPI check answers:

• Does this API have a public OpenAPI spec, and where is it?

• For an integration project, can I auto-generate a client library instead of writing one by hand?

• For competitive research, what is the full surface area of this API at a glance?

The cost of not finding the spec is hours of hand-coding what could be auto-generated. The fix is one round of well-known-path checks plus a quick scan of the API's documentation site. The OpenAPI specification itself lives at openapis.org and is free to use.

In one sentence: Find OpenAPI/Swagger specifications

Discovers OpenAPI (Swagger) specification files on a domain. Checks common paths for API (Application Programming Interface) documentation that reveals endpoint structure and functionality.

Don't worry if some of the words above are still unfamiliar — there's a plain-language glossary at the bottom of this page, and most of the terms link to their own beginner guides if you want to learn more.

Here's what's actually happening behind the scenes when you call this endpoint:

Searches for OpenAPI/Swagger files at common locations (/swagger.json, /openapi.json, /API-docs, /swagger-ui/, etc.). Supports detection of OpenAPI 3.1.0 and earlier versions. Validates discovered files and extracts API (Application Programming Interface) metadata including version, endpoints, paths, and server URLs.

If you're using an AI assistant through MCP, you don't need to understand any of the technical details — the assistant calls the tool and translates the result for you.

Let's skip the marketing fluff and answer the only question that actually matters: why should you, a real human with a real to-do list, care about the OpenAPI Detection tool? Here's the plain-English version, written the way you'd hear it from a friend who happens to do this for a living.

OpenAPI specifications reveal the complete API (Application Programming Interface) structure including endpoints, parameters, and authentication. This is valuable for API integration, security assessment, and competitive analysis.

Picture this in real life. Imagine a penetration tester. Here's the situation they're walking into: Discover API (Application Programming Interface) documentation to understand attack surface. Without the right tool, that person would be stuck copy-pasting between five browser tabs, reading documentation written for engineers, and crossing their fingers that the answer they cobble together is correct. With the OpenAPI Detection tool, the same person gets a clear answer in seconds — no spreadsheets, no guessing, no waiting for someone on the infrastructure team to free up.

Three questions this tool answers in plain English. If any of these have ever crossed your mind, the OpenAPI Detection tool is built for you:

• What is this website actually built with, layer by layer?

• Who hosts it, who runs analytics on it, who delivers the assets?

• Is the company on a stack that fits my product, my pitch, or my integration?

You can either click the tool and get the answer yourself, or ask your AI assistant — connected through MCP (Model Context Protocol) — to ask the question for you and translate the answer into something you can paste into Slack.

Who gets the most out of this. Sales teams qualifying leads, marketers researching competitors, partnership managers scoping integrations, and security teams looking for known-vulnerable software in the wild. If you see yourself in that list, this is one of the EdgeDNS tools you should bookmark today.

What happens if you skip this entirely. Skip it and you're guessing at how a website is built — which kills sales calls, integration scoping, and competitive research. That's why running this check — even once a month — is one of the cheapest forms of insurance you can give your domain.

If you're still on the fence about whether the OpenAPI Detection tool belongs in your toolbox, this section is for you. Below you'll meet three real people — a penetration tester, a developer, and a product manager — facing three real situations where this tool turns a stressful afternoon into a five-minute task. Read whichever story sounds closest to your week.

Story 1: API Security Assessment

Imagine you're a penetration tester. Discover API (Application Programming Interface) documentation to understand attack surface.

Why it matters: Map all API (Application Programming Interface) endpoints for comprehensive security testing.

Story 2: Integration Research

Imagine you're a developer. Find API (Application Programming Interface) documentation for third-party integration.

Why it matters: Quickly locate API (Application Programming Interface) specs without searching documentation sites.

Story 3: Competitive Analysis

Imagine you're a product manager. Analyze competitor API (Application Programming Interface) capabilities through their OpenAPI specs.

Why it matters: Understand competitor API (Application Programming Interface) features and structure.

Common situations across teams. Beyond the three stories above, here are the everyday workplace moments when people across the company reach for the OpenAPI Detection tool — or one of the tools right next to it in this category. If any of these are on your calendar this month, that's your sign:

• During sales prospecting, to qualify a lead by what they are running.

• During competitive research, to understand what a rival is built with.

• When scoping an integration or partnership.

• When you suspect a target is using a known-vulnerable version of something.

If you can see yourself in even one of those bullets, the OpenAPI Detection tool will pay for itself the first time you use it.

Still not sure? Here's the easiest test in the world. Open Claude, ChatGPT, Gemini, or any other AI assistant connected to the EdgeDNS MCP server and ask, in your own words: "Is the OpenAPI Detection tool useful for my job?" The assistant will look at the tool, ask you a couple of follow-up questions about what you're trying to accomplish, and give you a straight answer in plain English. No commitment, no signup forms, no jargon.

If you've connected the EdgeDNS MCP server to Claude, ChatGPT, Gemini, Cursor, or any other AI assistant, you don't need to write any code. Just ask in plain English:

"Use the OpenAPI Detection tool to check api.example.com and explain anything that looks wrong in plain language."

The AI will figure out which tool to call, fill in the right parameters, run it, and then explain the result back to you. No copy-pasting between tabs. No reading raw JSON. No memorizing endpoint names.

If you're a developer and want to call the endpoint from a script or your own application, here's the simplest possible example. Replace the placeholder API key with the real one from your dashboard.

There's just one piece of information you need to provide. The table below explains exactly what it is and what a real value looks like.

When you call this tool, you'll get back a JSON object with the fields below. If you're talking to it through an AI assistant, the assistant reads these for you and explains them in plain language — you don't need to memorize them.

These tools pair naturally with OpenAPI Detection. If you're already running this check, the related ones often answer the next question that comes up:

• API CORS Check — Analyze CORS configuration

• API Version Detection — Detect API versioning strategy

If you're using an AI assistant through MCP (Model Context Protocol), you can ask it to run several of these in one go: "Check OpenAPI Detection and the related tools for example.com and tell me what looks off."

If any words on this page felt like jargon, here's a plain-language version. Click any linked term to read a full beginner-friendly guide.

API (Application Programming Interface) — A way for one program to ask another program for something — like a waiter taking your order to the kitchen.

JSON (JavaScript Object Notation) — A lightweight format for sending data between programs. Looks like { "name": "example", "age": 5 }. Used by basically every modern web API.