A professional team collaborating around a large table covered with detailed technical blueprints and written specifications.

Specification-Driven Development

In a current project, I use a specification-first approach with OpenAPI as the single source for code and documentation generation. From this source, I generate:

  • Java backend API controller interfaces and DTOs
  • TypeScript frontend clients and models
  • API documentation

The benefits of this approach group into three main points:

  • Clearer API design:
    Defining schemas, statuses, and validation upfront creates a reliable and easy-to-use API
  • No manual syncing:
    Changes in the specification automatically rebuild and update all code
  • Component reuse:
    Shared schemas and parameters are actually shared, always

Quick sidetrack: In the same project, I also

  • Generate type-safe Java records from database tables using JOOQ, a Java SQL query builder
  • Build DSLs from grammar specifications with ANTLR4, a parser generator for custom languages

In all cases, the specification acts as the single source of truth. All downstream artifacts—code, documentation, and resources—derive from it.

Because this is a solo project, code generation is especially important. It stops me from wasting time on boilerplate code and keeps everything in sync without extra effort.