Undocumented APIs are unusable

You’ve built a working API. It has endpoints for books, authors, and reviews. It validates input with Zod, returns structured errors, handles pagination, and requires authentication. From a technical standpoint, it’s solid. But here’s the problem: nobody outside your team can use it.

The moment another team, a partner, or a frontend developer tries to integrate with your API, the first thing they ask is: “Where are the docs?” And right now, the answer is: “Read the source code.” That’s not going to work.

What clients actually need

Think about it from the perspective of someone who has never seen your codebase. They need to answer a series of very specific questions before they can make a single request.

What endpoints exist? They need to know the URL paths and which HTTP methods each one supports. Is it GET /books or GET /v2/books? Is creating a book a POST or a PUT?

What does the request look like? If they’re creating a book, what fields do they send? Is the author field a name or an ID? Is genre a free-text string or does it have to be one of a fixed set of values? What’s required and what’s optional?

What does the response look like? When they get a successful response, what shape is the JSON? What fields come back? Is the author embedded as a nested object or just an ID?

What happens when something goes wrong? If they send invalid data, what does the error look like? Is it { error: "bad request" } or { error: { code: "VALIDATION_ERROR", message: "Invalid input", fields: { title: ["Required"] } } }? The difference matters because they need to write code that handles those errors.

How do they authenticate? Do they need a token? What kind? Where does it go? A header? A query parameter? A cookie?

Without documentation, every single one of these questions becomes a guessing game. And developers do not like guessing games.

Why hand-written docs always go stale

You might think: “I’ll just write a README.” And that works, for about a week.

Here’s what happens. You write a nice document that describes your API:

# Books API (last updated: January 2024)

POST /books
  Body: { title: string, author: string }

Three months later, a developer follows those docs and sends { title: "Kindred", author: "Octavia Butler" }. They get back a 400 error. They’re confused. They double-check the docs. Everything looks right.

The problem? Somewhere along the way, your team renamed the author field to authorId because you switched to referencing authors by UUID instead of name. You also added a required genre field. But nobody updated the docs. The docs now describe an API that no longer exists.

This is not a hypothetical. This is what happens to every hand-written doc, on every project, every time. The API changes faster than anyone remembers to update the documentation.

What if the docs updated themselves?

Here’s the key insight that this entire course is built on: if the documentation is generated from the same code that defines your routes and validation, it cannot go stale.

Think about what you already have. Your routes are defined in code. Your Zod schemas describe exactly what each endpoint accepts and what constraints it enforces. All the information that documentation needs is already there, in your codebase. It’s just not in a format that anyone outside your team can read.

What if you could take those route definitions and Zod schemas and automatically produce a structured, machine-readable description of your entire API? That’s exactly what OpenAPI does. And that’s what we’re going to build in this course.

Change a Zod schema, and the docs update automatically. Add an endpoint, and it shows up in the docs. Remove a field, and the docs reflect it. No manual syncing. No stale documentation. No confused developers.

Exercises

Exercise 1: Look at one of your previous course projects. Imagine you’re a developer who has never seen the source code. Try to figure out what endpoints exist, what they accept, and what they return. Write down every question you’d need answered.

Exercise 2: Write a quick hand-written doc for three endpoints: list books, get a single book, and create a book. Include the request and response shapes for each one.

Exercise 3: Now go change a field name in the code (for example, rename author to authorId). Check whether your hand-written docs are still accurate. They probably aren’t.