Documenting APIs with OpenAPI

Code first or design first

You can build a shed and sketch it afterward, or draw it first and show the family before you buy any wood. APIs offer the same choice:

• Code first: write the API, and generate the spec from it. FastAPI does this from your type hints and serves it at /openapi.json, with docs at /docs.
• Design first: write the spec, review it with the people who'll call the API, then implement it and test against it.

Code first is faster for small teams. Design first catches design mistakes while they're still cheap to fix. Either way, the spec lives in git and changes are reviewed like code.

import json, re

routes = [
    {"method": "GET", "path": "/campaigns", "operation_id": "list_campaigns", "summary": "List campaigns."},
    {"method": "GET", "path": "/campaigns/{campaign_id}", "operation_id": "get_campaign", "summary": "Get one campaign."},
]

paths = {}
for r in routes:
    path_params = re.findall(r"{(\w+)}", r["path"])
    paths.setdefault(r["path"], {})[r["method"].lower()] = {
        "operationId": r["operation_id"],
        "summary": r["summary"],
        "parameters": [{"name": p, "in": "path", "required": True, "schema": {"type": "string"}} for p in path_params],
    }
print(json.dumps(paths, indent=1)[:600])

From OpenAPI to LLM tools

A tool definition for Claude has a name, a description and an input_schema. An OpenAPI operation has an operationId, a summary and parameter schemas. It's like copying a menu into another format: the dishes stay the same, and only the labels change. The match is almost one to one:

When the model calls the tool, your code turns its input back into a request: path parameters into the URL, query parameters into the query string, the body into JSON. This is how agents get access to a whole API at once, and how many MCP servers are generated.

Two cautions. First, descriptions written for developers aren't always good for models: a summary like "Get campaign" says nothing about when to use it. Second, don't expose every operation. An agent with a delete_all_campaigns tool will eventually use it. Pick a safe, useful subset.

import json

spec = {"paths": {"/products/{id}": {"get": {
    "operationId": "getProduct",
    "summary": "Fetch one product by id",
    "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}],
}}}}

def to_tools(spec):
    tools = []
    for path, methods in spec["paths"].items():
        for method, op in methods.items():
            params = op.get("parameters", [])
            tools.append({
                "name": op["operationId"],
                "description": op["summary"],
                "input_schema": {
                    "type": "object",
                    "properties": {p["name"]: p["schema"] for p in params},
                    "required": [p["name"] for p in params if p.get("required")],
                },
            })
    return tools

print(json.dumps(to_tools(spec)[0], indent=1))

op = {"operationId": "getItem", "summary": "Fetch one item"}
tool = {"name": op["operationId"], "description": op["summary"]}
print(tool["name"])

A spec for agents isn't a spec for people

Generating tools from a spec is quick, and it's easy to overdo. Two problems come up every time.

Don't expose every operation. A new assistant doesn't need every key on the company's key ring. An API with 200 endpoints makes 200 tools. Tool definitions cost tokens on every call, and the model chooses worse from a long list. It may also pick something dangerous, like a delete, when all it needed was to look. Choose the few operations an agent needs, and combine several into one where that fits the task.

Rewrite descriptions for the model. "Retrieves the resource" is fine in docs for a developer, who can read around it. A model decides what to call from that text alone, so say when to use the tool, what comes back, and what it doesn't do.

Keep the spec honest

A map is only useful if the roads still match it. Docs written by hand drift away from the real API, usually within weeks. So generate one from the other, or check them against each other in CI. If your code is the source, generate the spec from it. If the spec is the source, run tests that compare real responses against it.

A spec also lets a tool catch breaking changes automatically. Renaming a field, or making an optional one required, breaks clients that are already running. Tools such as oasdiff compare the old spec and the new one and fail the build, so you find out before your users do.