Stop Generating OpenAPI Specifications From Code!
API contracts, like OpenAPI, TypeSpec, or AsyncAPI, define the communication between servers and clients. They define URL paths, request bodies, responses, parameters, authentication, and more.
Most contract formats describe RESTful APIs since frameworks like GraphQL or gRPC have fixed contract formats baked into their tooling.
However, to materialize the benefits of API contracts, you need to create - and maintain - them. And here the software world is split into two camps.
Most modern languages offer open-source tools to generate OpenAPI specifications from server-side code. For this to work, the code is annotated with symbols that are translated into OpenAPI directives.
In the second camp, people write and maintain OpenAPI specifications by hand or with the help of tools like API-Fiddle, Swagger Next Editor, or Spotlight.
At first glance, the Code-First Approach offers many advantages. The tight coupling between server code and contract ensures the contract is never out-of-date. This makes the Code-First Approach seem more automated than manually keeping track of changes—lastly, version control systems for our code offer built-in governance mechanisms when using the Code-First Approach.
