In today's world, where software development has become an integral part of our daily lives, the design of Application Programming Interfaces (APIs) is a critical component. An API is a set of protocols and tools for building software applications, and it defines how different software components should interact with each other. There are two main approaches to designing APIs: Contract-First and Code-First.
In the Contract-First approach, the API's design is created before any code is written. This means that the API's specifications are defined in a contract or interface file, which outlines how the API will work, including its input and output parameters, data types, and protocols. Once the contract is finalized, developers can then generate the code for the API based on the contract's specifications.
On the other hand, in the Code-First approach, the API's design is created through the writing of code. Often there are annotations added to augment the source code. When the code compiles, an interface definition file can be destilled out of that code. This process appeals to many developers, because it happens in their natural habitat. It also ensures the descriptions is always in sync with the actual implementation.
The main drawbacks are: to change the definition, you have to change the code. This might result in compile errors and incompatibilities which prevent generating a new definition. Also, you have to understand the programming language and have the tooling installed.
Both approaches have their advantages and disadvantages, and choosing the right approach depends on the project's specific requirements and constraints. For the majority of projects I worked with, going contract first resulted in deeper thoughts about the actual requirements leading to a clearer API description before writing a single line of code (i.e. code that executes).
Looking at the API description, the underlying data structure emerges and the graphical user interface components arrange to a visual representation of the data.
OpenAPI specification
Once called swagger API description, it is now called OpenAPI and is a yaml/json file describing the available resources, data models and even security considerations.
Many tools support the visualization of that file, like the editor, plugins for your IDE or your code repository.
To utilize an OpenAPI specification file to generate classes (or whatever it is named in the programming language), have a look at this tip, too.