OpenAPI — API Specification

What is OpenAPI?

OpenAPI (formerly Swagger) is a standard way to describe your REST API in JSON or YAML. It lists every endpoint, what parameters they accept, what they return, and how authentication works. Agents read this to understand your API programmatically.

Example

Serve at /openapi.json:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Your API",
    "version": "1.0",
    "description": "What your API does"
  },
  "paths": {
    "/api/search": {
      "get": {
        "summary": "Search items",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Search query"
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "string" },
                      "title": { "type": "string" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Why it matters

Without OpenAPI, agents guess your API structure. With it, they can discover every endpoint, understand the parameters, and make correct requests on the first try.

Tips

Declare content-type in your responses so agents know what format to expect
Include description on parameters and schemas — agents use these for context
Most web frameworks can auto-generate OpenAPI from your route definitions

Spec maturity

Industry standard. OpenAPI 3.x is maintained by the OpenAPI Initiative. Universally supported by API tools, code generators, and AI agents.

Learn more