Hello everyone!
In this new post, we’ll cover an incredibly useful strategy that will help you save lots of time (and let’s be clear, mistakes too): using code generation tools.
These are the points we will follow today:
- What are code generation tools & Best alternatives
- Adapt them to your backend project
- Adapt them to your frontend project
- Automate the process on your CI/CD
- Conclusions
What are code generation tools & Best alternatives
Code Generation tools allow you to define all your APIs with the relevant complex input and output models (which includes primitive objects, composite objects, list, map, inheritance etc.).
Best Alternatives
-Protobuf or “Protocol Buffers”: this tool allows you to generate code by the protocol buffer compiler from your .proto files. It can also add generated API documentation for the provided source code.
-Swagger: the one we’ll cover in this post. It is an open-source software to build standard documentation in a human-readable format for REST APIs. This provides a UI to easily understand service contracts and consumers can interact with the service without any detailed knowledge of underlying logic.
Swagger is developed by SmartBear software and comes with tools like Swagger Editor, Swagger CodeGen, Swagger UI & Swagger Inspector.
Swagger has provided its specification known as OpenAPI specification, which we can follow while documenting REST APIs.
In that way, Swagger can be integrated with REST APIs in the following ways:
- A top-down approach – First API specification and then code generation. The one we’ll cover in this post.
- A bottom-up approach – First API code and then Swagger integration. This is quite familiar and most useful when there are already existing REST APIs built-in and Swagger documentation needs to be integrated.
Adapt them to your backend project
*(A quick mention here about the stack that we used for creating this post: Java 11, Spring, Spring Boot and Gradle).
To create an API contract, you can use the online Swagger Editor for the sake of simplicity. You can also download and install the same. To create the contract first have some understanding of OpenAPI specification. In order to write this specification, you’ll need to write your configuration on some YAML files.
After saving the specification in your .yml files, and in order to further generate source code, this swagger.yml file will be the source of input. To generate later on the code, we need to use the swagger-cli client in the command line. (You can of course automate this with a bash script).
java -jar swagger-codegen-cli-2.3.1.jar generate \ -i swagger.yaml \ --api-package com.thecodervalley.example.employee.api \ --model-package com.thecodervalley.example.employee.model \ --group-id com.thecodervalley.example \ --artifact-id spring-swagger-codegen-employee \ --artifact-version 0.0.1-SNAPSHOT \ -l spring \ -o spring-swagger-codegen-example |
Description of the arguments:
- i: Swagger specification source file
- api-package: Package information for generated API class
- model-package: Package information for the generated model class
- group-id: Maven properties
- artifact-id: Maven properties
- artifact-version: Maven properties
- l: Implementation framework, here Spring is used, which by default provides spring-boot
- o: Output directory
After having created your project from scratch, make sure you also automate the generation of all your input and output models. (Objects, DTOs, inheritance, lists, maps, etc).
Adapt them to your frontend project
Just a small mention here for all of you, frontend engineers! You can actually run the exact same cli generation command and configuration to generate Typescript code automatically.
Wouldn’t it be incredibly helpful and time-reducing to have the exact same API definition in both your backend and frontend projects?
Automate the process on your CI/CD
After running the generation commands in your service and model projects (both for the backend and the frontend clients), you can of course automate this process in a packaging and versioned way.
You can add these commands into bash scripts or trigger them from your .yml configuration files, (for example, the gitlab-ci.yml file for GitLab), so that every time you merge your project into the main branch, the code of your packages will be re-generated automatically and those projects will have a new automatic version created.
After that, you can just increase the version (either dynamically or manually) of your packages or libraries on either the Gradle or maven configuration files of your service project (or package.json files of your frontend projects).
Conclusions
As you can see, using this automation allows you to (after doing the configuration only once) be able to save infinite time and mistakes from your code as soon as you get this automation built. Cool, uh?
Hope you found this post useful!
If so, please subscribe to my newsletter for FREE! Cheers 🙂
