Configure OpenAPI documentation with examples — lab audio overview

Host: Welcome back. You're in Web APIs and Services for GenAI Engineers — a course about building the connection layer that lets applications, teams, and AI models actually talk to each other. This chapter is on FastAPI, which is one of the most popular Python tools for building these connections. And today's skill — auto-generating documentation for your own service — is something every team hits the moment more than one person needs to use what you built. Expert: Picture this. You're on a mid-sized engineering team, maybe fifteen or twenty people, and you've just shipped a service that does something useful with a large language model — summarizing support tickets, say. Now the mobile team wants to call it. The analytics team wants to call it. A partner company wants to call it. And every single one of them sends the same message: "Where are the docs? What do I send? What do I get back?" If your documentation is a stale text file someone wrote three sprints ago, you are about to spend your entire week answering questions in chat. Worse — people will guess, call your service wrong, and file bugs that aren't bugs. The teams that move fast are the ones whose documentation generates itself from the live code. When the code changes, the docs change. Nobody maintains anything by hand. That's the world you're stepping into today. Host: Okay, so this is exercise one — your starting point for the chapter. The chapter overview walked through the big picture of building web services. Now let's get specific. What exactly will we build? Expert: You're going to build a small service that does two things at once. First, it keeps a running list of every endpoint — every address — that your service exposes to the outside world. Think of an endpoint as a single door into your service, with a label on it like "summarize a ticket" or "fetch a user profile." Second, for each of those doors, your service will automatically produce a human-readable description of what it does, what it expects as input, and what it gives back. And here's the twist that makes this a GenAI course and not just a web course: some of those descriptions will be written by a large language model. Specifically, you'll use Google's Gemini — a family of AI models from Google — to generate polished, natural-language explanations of what each endpoint does, based on the raw information the code already knows about itself. So the key idea, the conceptual aha, is this: your code already contains most of the truth about your service. It knows what inputs each door accepts. It knows what it returns. It knows the names of things. Documentation doesn't have to be a separate artifact you maintain — it can be extracted. And where the raw extraction is too dry or too technical, you layer an AI model on top to translate it into something a human actually wants to read. That's the pattern. Extract the facts from the code, then let the model do the writing. Host: That sounds clean in theory. Before someone starts, what's the thing that trips people up here? Expert: Two things. The first is trusting the model too much. When you ask a language model to describe what an endpoint does, it will happily make things up if you don't give it enough real information to work from. It will invent parameters. It will claim the service does things it doesn't do. So the tip is: feed the model the actual, structured facts your code already has — the endpoint's address, its inputs, its outputs — and ask it to rephrase, not to invent. Keep the model on a short leash. Your prompt to it should basically say: "Here are the real facts. Make them readable. Do not add anything." The second thing is this. When you're registering endpoints — keeping that running list I mentioned — it's tempting to do it manually, typing out each one. Don't. The whole point of auto-generation is that adding a new door to your service should automatically add a new entry to the docs. If a human has to remember to update a list every time they add a feature, the list will drift out of sync within a week. So as you build, keep asking yourself: if a teammate adds a new endpoint tomorrow and forgets about the docs, do the docs still update correctly? If the answer is no, you've built the wrong thing. Host: Good warning. So when someone finishes this, what can they actually do, and what's next for them? Expert: After this exercise, you'll be able to take any Python web service and produce living documentation for it — documentation that stays accurate as the code evolves, and reads like a human wrote it, because a language model polished the phrasing. That's a genuinely valuable building block. Your team can use this as the foundation for a developer portal, an internal service catalog, or an onboarding tool that helps new engineers understand what your organization's services actually do without pinging six people on chat. And because this is the only exercise in this chapter, when you finish, you've got the complete capability — a working implementation of AI-assisted, self-updating API documentation that you can bring straight into your team's architecture discussions. That's the kind of production skill GenBodha is built to teach. Go build it. Thanks for listening.