OpenAPI spec
An OpenAPI spec is the YAML / JSON description of a REST API — endpoints, params, responses, auth — used to drive doc generation, SDK generation, mock servers, and increasingly AI-readable API surfaces in 2026.
OpenAPI (formerly Swagger) is the de-facto standard for describing REST APIs. Spec content: paths + methods, params with types, request / response schemas, auth schemes, examples. Tools built on top: Swagger UI / Redoc / Mintlify / ReadMe for docs, Stainless / Fern / Speakeasy / OpenAPI Generator for SDK gen, Prism for mocks, postman / insomnia for collections. In 2026 OpenAPI specs also drive LLM tool definitions — many MCP servers wrap an OpenAPI spec, and Claude / GPT can be given OpenAPI YAML directly as tool specs. The richer + more accurate your OpenAPI, the more downstream tooling 'just works'.
When to use openapi spec
- Any REST API.
- AI tool / agent integrations.
Common mistakes
- Hand-writing OpenAPI then drifting from the code — auto-generate from server code where possible.
- Missing examples — generated docs + SDKs look thin.
FAQ
What is openapi spec?
An OpenAPI spec is the YAML / JSON description of a REST API — endpoints, params, responses, auth — used to drive doc generation, SDK generation, mock servers, and increasingly AI-readable API surfaces in 2026.
When should I use openapi spec?
Any REST API. AI tool / agent integrations.
What are the most common mistakes with openapi spec?
Hand-writing OpenAPI then drifting from the code — auto-generate from server code where possible. Missing examples — generated docs + SDKs look thin.
Related terms
- AI docs — AI docs is the documentation category where AI-native features (semantic search, Q&A chat, auto-summary, code-example generation) are first-class — Mintlify AI, ReadMe AskAI, GitBook AI, Algolia AI Search are 2026 leaders.
- Model Context Protocol (MCP) — Model Context Protocol (MCP) is Anthropic's open standard for connecting AI assistants to external data sources and tools — letting any compliant client use any compliant server's capabilities.
Sources
Last updated: 2026-06-01. Raw markdown: https://promtable.com/glossary/openapi-spec.md.