Prompt
How do I keep docs in sync with changing request bodies?
Latest observation
A good way to keep docs in sync with changing request bodies is to make the request body schema the source of truth and generate the docs from it, rather than writing docs by hand.
Practical approaches
1. Use an API schema/spec
Define request bodies in something like:
- OpenAPI / Swagger
- JSON Schema
- TypeScript types + schema library (e.g. Zod, io-ts)
- Protocol Buffers / gRPC if applicable
Then generate:
- human-readable docs
- client SDKs
- validation rules
- examples
This reduces drift because one schema change updates everything.
2. Generate docs from code
If you’re using a framework, annotate the request model in code and auto-generate docs:
- SpringDoc / Swagger annotations
- FastAPI / Pydantic
- NestJS Swagger
- ASP.NET Swashbuckle
- Django Ninja / DRF schema tools
This works best when the code model is the contract.
3. Validate docs in CI
Add checks that fail if docs and implementation diverge:
- diff generated OpenAPI against committed spec
- run contract tests
- ensure example payloads still validate
- lint schema changes
4. Version your API
If request bodies change in incompatible ways:
- create versioned endpoints (
/v1,/v2) - or version the schema
- document deprecations and migration paths
This avoids trying to keep one doc set accurate for two different contracts.
5. Include examples that are generated or tested
Store sample request bodies as fixtures and use them in:
- docs
- tests
- mocks
If a body changes, the examples fail tests and get updated.
6. Keep docs near the code
Docs in the same repo as the API implementation are easier to maintain than separate manual docs. Prefer:
- inline schema definitions
- doc generation in the build pipeline
Rule of thumb
If your request bodies change often, don’t handwrite them in docs. Instead:
- define a schema,
- generate docs from it,
- enforce consistency in CI.
If you want, I can show a concrete workflow for your stack, e.g. OpenAPI, FastAPI, Node/TypeScript, or Spring Boot.