OpenAPI (Swagger) is the language-agnostic specification for describing RESTful APIs that serves as the single source of truth for API documentation, client code generation, and automated testing — enabling teams to define their API contract in a YAML/JSON file and automatically generate interactive documentation, type-safe client SDKs, server stubs, and API validation from that single definition.

What Is OpenAPI?

• Definition: A standard specification (formerly Swagger, now OpenAPI Specification maintained by the OpenAPI Initiative) for describing REST API endpoints — defining paths, HTTP methods, request/response schemas, authentication, and examples in a structured YAML or JSON document that both humans and machines can read.
• Machine-Readable Contract: An OpenAPI spec is not just documentation — it is a machine-readable contract that tools can use to generate client code, validate requests, run API tests, mock servers, and power AI agent function calling.
• Swagger Origin: The OpenAPI Specification evolved from the Swagger specification created by Wordnik in 2011 — Swagger tools (Swagger UI, Swagger Codegen) remain the most popular ecosystem around OpenAPI.
• Version: OpenAPI 3.1 (current) aligns with JSON Schema — the most widely supported version is 3.0.x, with 2.0 (Swagger) still found in legacy systems.
• Auto-Generation: FastAPI, Django REST Framework, and other modern web frameworks automatically generate OpenAPI specs from code — developers annotate their endpoint functions and the framework produces the spec.

Why OpenAPI Matters for AI/ML

• LLM Function Calling: OpenAI's function calling and Anthropic's tool use accept OpenAPI-compatible JSON schemas for tool definitions — an OpenAPI spec for a tool API can be directly used to define LLM tools, enabling AI agents to discover and call APIs automatically.
• AI Agent API Integration: GPT plugins, AutoGPT, and LangChain's OpenAPI agent read OpenAPI specs to understand how to call external APIs — agents can browse a spec and construct valid API calls without hardcoded integration code.
• Model Serving Documentation: FastAPI ML model serving endpoints automatically produce OpenAPI docs at /docs — data scientists and engineers explore the API interactively via Swagger UI without reading source code.
• SDK Generation: OpenAPI Codegen produces Python, TypeScript, Go, and Java client SDKs from the spec — ML platform APIs can offer official SDKs without manually maintaining client libraries in each language.
• Contract Testing: Schemathesis and Dredd automatically test API implementations against their OpenAPI spec — verify that the FastAPI model serving endpoint honors its documented request/response contract.

OpenAPI Spec Structure: openapi: "3.1.0" info: title: ML Inference API version: "1.0.0"

paths: /v1/embed: post: summary: Generate text embeddings requestBody: required: true content: application/json: schema: type: object required: [texts, model] properties: texts: type: array items: {type: string} maxItems: 100 model: type: string enum: ["text-embedding-3-small", "text-embedding-3-large"] responses: "200": description: Embeddings generated successfully content: application/json: schema: type: object properties: embeddings: type: array items: type: array items: {type: number} "422": description: Validation error

FastAPI Auto-Generation: from fastapi import FastAPI from pydantic import BaseModel

app = FastAPI(title="ML Inference API", version="1.0.0")

class EmbedRequest(BaseModel): texts: list[str] model: str = "text-embedding-3-small"

@app.post("/v1/embed") def embed(request: EmbedRequest) -> dict: return {"embeddings": embed_model.encode(request.texts).tolist()}

OpenAPI spec auto-generated at /openapi.json

Interactive docs at /docs (Swagger UI) and /redoc

LLM Tool Use from OpenAPI: import requests, yaml spec = yaml.safe_load(requests.get("https://api.example.com/openapi.yaml").text)

Use spec to construct LangChain OpenAPISpec agent

from langchain.agents.agent_toolkits import OpenAPIToolkit toolkit = OpenAPIToolkit.from_llm(llm, OpenAPISpec.from_spec_dict(spec))

OpenAPI is the contract-first API definition standard that transforms REST API development from ad-hoc documentation to automated, machine-readable interface specification — by capturing the full API contract in a structured YAML file, OpenAPI enables the entire ecosystem of documentation generation, client code generation, AI agent integration, and automated testing to be driven from a single authoritative source of truth.