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.