API Documentation (Swagger/OpenAPI)

A friend of mine works at a mid-size fintech. Their payments team built a new endpoint for processing refunds. The mobile team was supposed to integrate with it. Simple enough.

Except nobody documented the API. The payments team said "just look at the code." The mobile team looked at the code, misunderstood a field called amount (was it cents or dollars?), and shipped to production. For three hours, every refund was 100x what it should have been. Customers got $5,000 back instead of $50.

Total damage: roughly $50,000 in over-refunds before someone noticed.

All because there was no API documentation. No contract. No shared source of truth. Just a Slack message that said "the endpoint is /api/refunds, POST, you'll figure it out."

API documentation isn't bureaucracy. It's the contract between teams. Without it, you're building on assumptions. And assumptions in distributed systems have a funny way of turning into production incidents at 2 AM.

One line in a spec would have prevented all of it, and it is worth seeing exactly which line.

API documentation is a structured description of what an API does, what it expects, and what it returns. Think of it like a restaurant menu, it tells you what's available, what ingredients are in each dish, and what you're going to get when you order.

But we're not talking about a wiki page someone wrote six months ago and never updated. We're talking about machine-readable specifications that can generate documentation, client SDKs, test suites, and mock servers automatically.

The industry standard is OpenAPI (formerly known as Swagger). Here's what it looks like at a high level:

openapi: 3.1.0
info:
 title: Payments API
 version: 1.0.0
paths:
 /refunds:
 post:
 summary: Process a refund
 requestBody:
 content:
 application/json:
 schema:
 type: object
 properties:
 transaction_id:
 type: string
 amount_cents:
 type: integer
 description: Refund amount in cents (not dollars!)
 required:
 - transaction_id
 - amount_cents
 responses:
 '200':
 description: Refund processed
 '400':
 description: Invalid request

Notice amount_cents, not amount. That single naming decision, documented in a spec, would have prevented the $50,000 incident.

Swagger vs. OpenAPI. What's the Difference?

People use these terms interchangeably, but they're technically different: