What are OpenAPI specifications and why are they important?

What you need to know

An OpenAPI document has a few main parts:

Who uses it

• People: Swagger UI at /docs and ReDoc at /redoc render it for humans.
• Client generators: openapi-typescript or openapi-generator create typed SDKs, so the front-end never hand-writes fetch calls.
• Infrastructure: API gateways, mock servers and contract tests read it.
• AI agents: a parameter schema is already JSON Schema, which is what LLM tool definitions use.

From OpenAPI to an LLM tool

1from typing import Annotated2from fastapi import FastAPI, Query3from pydantic import BaseModel45app = FastAPI(title="Orders API")67class OrderStatus(BaseModel):8    order_id: str9    status: str10    eta_minutes: int | None = None1112@app.get("/orders/{order_id}", operation_id="get_order_status",13         summary="Get the delivery status of one order")14def get_order_status(order_id: str,15                     include_eta: Annotated[bool, Query(description="Also return ETA")] = True) -> OrderStatus:16    ...1718def openapi_to_tools(spec: dict) -> list[dict]:19    tools = []20    for path, ops in spec["paths"].items():21        for method, op in ops.items():22            params = op.get("parameters", [])23            tools.append({24                "name": op["operationId"], "description": op["summary"],25                "input_schema": {"type": "object",26                                 "properties": {p["name"]: p["schema"] for p in params},27                                 "required": [p["name"] for p in params if p.get("required")]}})28    return tools

openapi_to_tools(app.openapi()) really produces a tool named get_order_status with the summary as its description, an input schema with order_id (string, required) and include_eta (boolean, default true, "Also return ETA"). The agent can now call your endpoint, and when you change the route, the tool changes with it. Libraries such as FastMCP can build a whole MCP server from an OpenAPI spec in the same spirit.

Set operation_id and summary deliberately: they become the tool's name and the text the model reads to decide when to call it.

A real-life example

A quick-commerce company has an orders service in FastAPI, a React web app, an Android app and a support agent built on an LLM. Before, each team wrote its own client and its own idea of the order status values. When the backend added a new status, rider_reassigned, the Android app crashed on the unknown value.

Now the status is a declared Enum in the schema. CI regenerates the TypeScript and Kotlin clients from /openapi.json on every backend release, and a contract test fails if a change would break an existing client. The support agent's tools are generated from the same spec, so it learned about rider_reassigned with no prompt edits.

Follow-up questions to expect

• "What is the difference between OpenAPI and Swagger?" — Swagger was the original name of the spec; since version 3 the spec is OpenAPI, and "Swagger" now means the tools such as Swagger UI.
• "How do you make the spec more useful?" — Return types on every route, responses= for error codes, field descriptions and examples, and clear operation_id values.
• "Should the spec be public?" — For internal services, often not: disable the docs routes in production and publish the spec to an internal portal or registry instead.