Keeping API documentation beside the route handlers

The working rule for this walkthrough is simple: generate the API contract from code, then write explanations around that contract. Keep request fields, response schemas, and route descriptions close to the implementation. Use an assistant for editorial work, not as the authority on endpoint behavior.

We will use a small FastAPI service with a POST /summaries endpoint. The goal is a repeatable documentation build, a tested example, and a review process that catches changes before publication.

§ Step 1: Define the public boundary

Start with separate request and response models. For this example, define SummaryRequest with a required text field and a SummaryResponse containing summary and request_id. Avoid exposing an internal database model just because it already contains similar fields.

Attach SummaryResponse to the route through response_model. FastAPI uses the declared response model for documentation, validation, and output filtering. That makes the public response shape an explicit implementation decision rather than an assumption in a separate document. ([fastapi.tiangolo.com](https://fastapi.tiangolo.com/tutorial/response-model/))

Before moving on, decide which fields are required, which accept null, and which have defaults. Treat these as separate questions during review.

§ Step 2: Put explanations beside the handler

Add a short route summary, a useful description, and a tag such as Summaries. FastAPI supports these operation-level metadata fields and can use a handler's docstring as its description. ([fastapi.tiangolo.com](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/))

Write the description around observable behavior. State whether whitespace is preserved, what length limits apply, and whether the operation stores submitted text. Include only behavior you have verified in the implementation.

• Purpose: Explain the result the caller receives.
• Constraints: Describe accepted input and enforced limits.
• Failures: Record implemented error responses and recovery guidance.
• Side effects: State any storage or background processing.

§ Step 3: Generate the OpenAPI artifact

Use app.openapi() in a small repository build script to obtain the generated schema, then serialize it to openapi.json. FastAPI's OpenAPI generation uses the application's registered routes; keep this export tied to the same application factory used by your service. ([fastapi.tiangolo.com](https://fastapi.tiangolo.com/how-to/extending-openapi/))

Give the script a stable command in your project tooling. Configure it to avoid production credentials and external network calls during application initialization. Sort serialized object keys so a schema comparison is easier to review.

Inspect the artifact now. Confirm that POST /summaries appears, its request body references the intended schema, and its successful response contains only public fields.

§ Step 4: Check the rendered reference

Run the service locally and open /docs. FastAPI provides Swagger UI there by default, with the OpenAPI schema available at /openapi.json. Both locations are configurable. ([fastapi.tiangolo.com](https://fastapi.tiangolo.com/tutorial/metadata/))

Read the page as someone seeing the endpoint for the first time. Check field descriptions, required markers, response types, and operation names. If something is wrong, fix its source declaration and regenerate rather than editing the exported JSON by hand.

§ Step 5: Test the documented example

Create a synthetic input such as a short meeting note. Submit it through FastAPI's TestClient, which supports request calls and assertions against response status codes and JSON bodies without running a separate HTTP server. ([fastapi.tiangolo.com](https://fastapi.tiangolo.com/tutorial/testing/))

Assert the stable parts of the contract: the status code, required keys, and value types. If summary generation depends on an external model, replace that dependency in the test. Keep a separate integration check for the real upstream connection.

§ Step 6: Add an assistant review pass

For the editorial pass, use an existing coding assistant or SDK configured for Vana API. Its documented client setup includes Claude Code, Codex, Gemini CLI, and OpenAI-compatible clients, with protocol-specific base-path conventions. ([vanaapi.com](https://vanaapi.com/))

Provide only the relevant handler, public schemas, and sanitized test fixture. Ask for a description grounded in those files, with unsupported behavior listed as questions rather than filled in. Create a Vana API account if you want to try this review step in your own workflow.

§ Step 7: Publish with the release

Add schema generation and example tests to continuous integration. Compare the resulting artifact with the previous release, and require review for removed fields, new requirements, or changed response types.

Publish the reference from the same commit as the service. Keep human-written guides beside it, but let the generated contract carry the exact field definitions. The final check is practical: can a reader make one successful request without consulting the handler?