What is API Design First Approach
Overview
The Code First approach is a more traditional approach to building APIs, with the development of code happening after the business requirements are laid out, eventually generating the documentation from the code. The Design First approach advocates for designing the API’s contract first before writing any code.
The concept of the API starts with the business team identifying an opportunity. The opportunity is analyzed and a plan to capitalize on it is created in a text document by strategists, analysts, and other business folks. This document is then passed along to the development team, where the development of the API happens in two main ways
- Design First: The plan is converted to a human and machine-readable contract, such as an OpenAPI specification document, (Swagger document) from which the code is built
- Code First: Based on the business plan, API is directly coded, from which a human or machine-readable document, such as a Swagger document can be generated
Design first approach over code first approach
- The biggest reason to go for the Design First approach is when your API’s target audience is external customers or partners. The API contract or the OpenAPI specification can be visualized with tools like Swagger UI which depicts the inputs and outputs in a more human-readable manner.
- The API contract can act as the central draft that keeps all the team members aligned on what the API’s objectives are, and how the API’s resources are exposed. It’s easier for teams to reduce any mismatches between the integrations.
- Sometimes with open-source tools, it’s possible to auto-generate stub codes against the OpenApi specification document with a considerable amount of initial code wiring which can boost the time to market.
Design philosophy
There are 2 main opensource libraries that can be utilized to create the server stubs from the OpenAPI spec (2.0 and 3.0).
Proceeding with openapi-generator
In terms of capabilities, both of the libraries are the same, in fact, most of the base code is equal. However, the open API generator is more active and driven by the community and is documented ahead of the swagger-codegen.
Swagger Codegen is driven by SmartBear while OpenAPI Generator is driven by the community. More than 40 top contributors and template creators of Swagger Codegen have joined OpenAPI Generator as the founding team members. For more details, see the Fork Q&A. Read more here.
The integration
There’s a plethora of languages and frameworks supported by the OpenAPI Tool and however it misses the spring Gradle-based stub generation. It offered a maven-based implementation only. So, there are some amendments done in the initial integration to cater to this and bring support to the Gradle-based spring-boot applications.
The integration is done through org.openapi.generator Gradle plugin with the intention of generating the controllers(API) and dto(models) automatically against the provided OpenAPI specification document.
The implementation
The boilerplate code can be found here https://github.com/Gonzalliz/api-design-first-template. Follow the README to run the application locally.
Changes and suggestions are welcome !!
Points to consider
- Auto-generated stubs by openapi-generator library follow code standards constrained by the library creators
- The openapi-generator library and its dependencies work for spring-boot version
2.5.4but not for the latest2.6.2as of Jan 10, 2022, hopefully, openapi-generator associatedspringfox-swagger2andspringfox-swagger-uilibraries will be made compatible with the latest spring-boot versions.
