Over the past couple of years, I’ve been part of a dynamic team of 12 engineers. Wrangling all our API Dtos, models, and TypeScript objects to stay in harmony has been quite the adventure! Whenever we need to tweak a DTO, it’s like embarking on a treasure hunt: “Where does this ripple effect lead? Will adding a new field here trigger a cascade of chaos elsewhere?”

Issue #1: Syncing Struggles

The other biggest issue, is that for each and every DTO on our backend, we need the same TS type for the frontend, and this was often seen as a productivity drainer, as this was leading to duplicated code within the backend and frontend, many bugs due to some changes in the backend not reflecting the types in the frontend and so on.

The pluggin

Intellij Swagger 3 Java plugin by Gustavo de Souza
For these reasons and many more. I have adopted Swagger 3 in our project, in fact the frontend team has been really happy getting all types auto generated out of the box with Swagger 3 and OpenAPI specs, however, they were not satisfied with documenting all the current endpoints that they already use and migrating them, for this reason I have build the Java Swagger 3 Generator that added support to a few actions and some “magic” tricks behind the scenes.

Swagger Generator Actions Intellij by Gustavo de Souza
If you’re diving deep into Swagger 3 territory and craving a shortcut to endpoint enlightenment, behold the plugin! Here’s a taste of its powers:

Calling All Swagger Fans!

If you feel that you heavily use Swagger 3 to your projects and are trying to find something that will boost documenting endpoints, I would suggest giving a try to the plugin.

And the most important one is SwaggerGenerate that will auto add Swagger annotations to Models, Dtos, Controllers …

This action will run a few checks in the current class and define which one it could be e.g

• Controllers
  Will add @Tag annotations and map all methods that have any Spring REST annotations and/or Jax-RS annotations.

• Models / DTO’s
  Will add @Schema annotation for any field, and mark them as required or not based on type, validations, and other constraints, fully supporting javax.validation.* or jakarta.validation.*

The fact that just by creating something simple, that can help you, your team, and even make the engineers a bit more happy, is satisfying and has a nice feeling. Sometimes we tend to focus on solving only our daily tickets, or building things that were planned in the previous spring, however, many times we can step out a bit, and look things from a different perspective, and in fact create something that will benefit everyone around you.

Sometimes, being a better engineer is as simple as lending a hand to your fellow engineers. Forget the daily grind; let’s sprinkle a little happiness dust on our projects! By thinking outside the code, we can craft solutions that make everyone’s day a little brighter.

Source code on Github :)

— — — — —

So, if you dug this article and crave more tech tales, dive deeper into the world of Swagger and watch the magic unfold!