You own a FastAPI service. It has been running for a while, and someone on your team just asked to point an SDK generator at it. Another person wants a contract test. A third wants a documentation UI. You open /openapi.json, see a document that FastAPI wrote for you, and assume you are done.
This is the situation a recent Scalar post speaks to. In OpenAPI with FastAPI, part one of a three-part, vendor-neutral series, Scalar notes that FastAPI generates an OpenAPI document automatically from type hints, Pydantic models and decorators, served at /openapi.json. Then it says the sentence most FastAPI teams need to hear: "The interesting work is not turning it on. It is making the document accurate enough that other tools can rely on it."
The advice is plain FastAPI and Pydantic, and it applies, in the post's words, "whatever you later point at the document: a documentation UI, an SDK generator, a linter, or a contract test." So whichever of your three requests lands first, the same work serves all of them.
Start with versions, because this is the warning that may bite you soonest. Since FastAPI 0.99.0 the output is OpenAPI 3.1.0 with JSON Schema 2020-12. That means nullable fields come out as anyOf with a null type, which, as the post puts it, "catches people who feed the document to a tool that only reads 3.0." If any tool in your chain is a 3.0-only reader, you will see it there. The post also pins its own claims: behaviour is described "as of September 2026, when the latest release was 0.141.1." There are no other figures, and that version pin is itself a habit worth copying.
Next, errors, which the post names as the most common gap. FastAPI knows your success response and adds a 422 for validation. But "it does not know about the 404 you raise with HTTPException inside the function, because that happens at runtime." If your handlers raise errors like that, your document is quietly silent about them. The fix is to declare every response, and to give each a model when the body has a shape.
The smaller advice adds up. Give tags descriptions, because SDK generators use them as namespaces. Use docstrings as operation descriptions. Write explicit summaries for functions named something like handle_v2_lookup, so nobody downstream has to guess what they do.
Now the turn that makes this more than a tutorial. The APIs.io catalog holds Scalar as one of the better-described tool vendors, so it is fair to ask whether Scalar's own record follows its own advice. The provider page lists API pages for its products: Scalar API References, which renders documents like the one you are working on, the Scalar Registry that stores them, and Scalar SDKs that generate from them. On the Agent Readiness score, the MCP server, agent skills, a well-known catalog, error semantics, examples and the full identity layer are all lit.
The Kin Score is 70.8, in the exemplar band, carried by contract quality at 78.1 and developer ergonomics at 73.2, with contract governance lower at 45.5. The Agent Readiness score is 57.6, agent-ready. The post's central advice, document every response including the errors raised at runtime, is the error semantics dimension written as a FastAPI tutorial, and Scalar's own record lights it.
The catalog also shows what is not lit: idempotency, dry-run mode and the agent card. So the record is good, not perfect, and it is worth saying so.
What you take away is practical. Before you hand your FastAPI document to anything else, check three things: that your tools can read 3.1 and its anyOf-with-null nullable fields, that every response your handlers can produce is declared, including the runtime 404s, and that tags, docstrings and summaries say what the operations are. Scalar has written the guide that turns a generated document into one other tools can trust, and its own contract already follows most of it. Parts two and three are still to come.
Read the original: https://apis.io/2026/10/21/scalar-says-the-interesting-work-is-making-the-fastapi-openapi-accurate/