openapi
**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.