Over the years, web development has moved away from a monolithic architecture. This approach means that all code for a site is contained in a single solution. Instead, modern architectures allow for different services being combined to create the overall site. This architecture has many benefits, such as allowing developers to work on each part independently with new features or bug fixes.
However, there are challenges to this approach too. One of these is keeping the interfaces that services expose in sync across the whole system. This challenge can be particularly obvious when the code in question is not written in the same language. For example, a site may have a UI written in typescript, that needs to communicate with RESTful APIs.
Here at Ethisys, we have been using an open source solution to generate these interfaces from Swagger documentation. It’s a simple idea, but one that can save a lot of time and hassle for developers. It means that all the interface changes can be regenerated from the Swagger documentation that is produced. Plus, importantly, the documentation actually matches the API that is deployed! As opposed to an old definition being used that is very likely not updated accurately as the API is developed.
A further enhancement we suggest is to actually put the command used to generate the interfaces in the package.json file. This means that any developer can run the command to regenerate the interfaces with the same parameters. It’s a simple step you can take to keep the whole development team working together effectively.