Why schema first

Broadly speaking there are two approaches people take to maintaining API specifications:

• Schema first, where you write the schema by hand
• Code first, where you generate the schema from your code

This project being a code generator from API specification files is on the schema first side of the debate, but why?

Ultimately this is fairly subjective, but there are four primary motivators that lead us to believe schema first is the better approach.

This is also recommended by the OpenAPI initiative (OAI) itself, where they refer to this as “Design-first” with similar arguments

Longevity

APIs are forever, changing them in backwards incompatible ways is hard/expensive, or sometimes not possible.

With that in mind, we believe it’s important to be thoughtful about your API design, and that writing an explicit specification/contract is a great forcing function to accomplish this.

Additionally, programming languages / frameworks come and go - they are an implementation detail, and subject to change as business requirements evolve. OpenAPI (originally Swagger) has been around for over a decade now, and we’re confident it’ll be around for a long time.

Common Language

Many large projects / systems will involve multiple programming languages. For example, you might have a Java backend, Kotlin Android app, Swift iOS app, and Typescript web frontend.

For writing your API contracts using OpenAPI up front, you create a common ground for developers of all languages to discuss and hash out the details.

Constraints

General purpose programming languages are very flexible. If you try hard enough, you can probably implement it. Specifications like OpenAPI on the other hand are more rigid and constraining.

We believe it’s better to lean into this and design your system such that it can be represented fully by a specification, rather than attempt to generate a specification from the implementation and lose information/nuance in the process.

Separation

A good specification not only defines the API contract, but also includes a lot of supplementary information such as examples, and documentation.

Generating a good specification from your code, therefore requires including all this extra metadata in the code, which can make the code more difficult to work with.

We prefer to separate these concerns out into the specification, and keep the implementation code leaner and simpler.