Manual OpenAPI spec maintenance creates a familiar problem: your YAML is outdated by the next commit. Code-first generation tools promise to fix this by deriving specs directly from your route handlers.
Codehooks.io's latest release exemplifies the approach. Pass a Zod schema to app.crudlify(), add app.openapi(), and you get eight CRUD endpoints with full Swagger UI documentation at /docs. The platform supports Zod, Yup, and JSON Schema, converts schemas automatically, and lets you filter internal routes from public docs.
For custom endpoints beyond CRUD, developers use OpenAPI middleware decorators - a pattern familiar from NestJS and Fastify implementations. The code example shows clean integration, though notably simpler than equivalent Express or NestJS setups.
The broader ecosystem
This isn't new territory. FastAPI has offered automatic OpenAPI schema generation since 2018. NestJS users rely on decorator-based approaches. Express developers typically choose between express-openapi-validator for runtime validation or tools like fastify-zod-openapi for type-safe generation.
The trade-offs matter. Code-first tools eliminate drift between implementation and documentation - a real problem when manual specs lag behind production code. But OpenAPI Generator, with 6,800 GitHub forks, still draws complaints about "lackluster" client generation quality across languages. Recent bug reports note Gradle failures with webhooks definitions in v7.10.0.
What works, what doesn't
Schema-to-spec generation is solid. Runtime validation works. The friction point remains generated client code - developers on HackerNews consistently prefer writing clients manually over using generated output, particularly for languages beyond TypeScript.
For internal services or teams controlling both API and consumers, tools like Codehooks.io reduce maintenance overhead. For public APIs where you don't control client implementations, the spec quality matters more than how you generated it.
The pattern is established: FastAPI showed automatic schema generation works at scale. The question isn't whether to generate specs from code - it's which tool fits your stack and whether you need the generated clients. History suggests treating code generation as a documentation convenience, not a replacement for thoughtful API design.
Worth noting: the broader API management market exceeds $5B, but tooling for spec generation remains fragmented across frameworks. No dominant standard has emerged beyond "use whatever your framework supports."