Writing an API client for your Rest API with Swagger code-gen

As a backend developer, several times I have been in the situation where I create the endpoints that are exposed through a REST Api. From there, a frontendmobile team, etc… consumes it and then the magic happens.

Consumption of an api through different clients

Consumption of an api through different clients

The clients that consume the api are normally http client wrappers, where they have models that map to the response and interceptors for specific status codes. In the microservices and distributed systems era, I realized this work is fairly usual and I wondered for some time the idea of having a generator for writing an api client based on a specification. (If you have created cloud endpoints on Google Cloud, you may have found really useful the clients it can generate for you out of the box).

The main benefits (in my opinion) of writing the api client automatically are:

  • Apis can change and their clients be obsolete. The design should be kept in mind at any time after the api goes to the production environment. Until then, writing and consolidating the implementation of the api client may be difficult. In my experience, writing this code is similar to boilerplate (http client creation, handling of the status codes, creating model to wrap the http responses… )
  • Possibility to extend the generation of clients to different languages: today we may need an api client for Android, tomorrow for iOS, etc…
    • This could be great for a company that is based on api services and want to reach a wider community of developers.

The main disadvantages, as far as I can see, are:

  • Maintaining code that is not created automatically (like custom authentication that cannot be generalized).
  • Flexibility: the code generated forces you to consume the api in a specific way. This could be seen also as an advantage if there is a policy about how to perform requests/consume api endpoints (Ex: some client apps may have to inject some custom headers based on a timestamp.)

Based on that, I tend to take this client generation as a skeleton for the code or as a initial step to test my api. Some generations may require a second iteration to get the api client ready for production and use. In the past, i have not done lot of custom code apart from the code generation, so I would recommend to give it a go. Furthermore, the api clients can be used on a first step for QA when performing regression tests.

For this post, we will create an api for exposing resources related to a video store. To keep it simple, we will create a Spring Boot app with endpoints that expose a ‘Video‘ resource. After this we will go through the generation of a client and its use.

 

Building the service

All the steps followed in this post can be found on github. There, you will find  the web service implementation an the clients generated.

The service is going to expose a Video resource. In order to do that we will use:

  • Spring starter web for exposing the endpoints.
  • JPA as the persistence api for communicating to the datasource.
  • H2 as the database: A in memory solution (so you can test on your machine without additional setup).
  • Swagger 2 for auto-documentation on the endpoints exposed.

The dependencies on our pom.xml would look like:

Once the dependencies have been pulled, we proceed to setting up the model Video:

As we are using JPA as the way to work with persistence, writing a CRUD repository should be as easy as:

Once, we have the repository layer, we proceed with the controller. A possible implementation could be:

Having all the layers done, we should be able to start using the endpoints.

You can test the service running the application with:

And then hitting a service url. For example:

After checked, this, we are going to start adding some configuration in order to add Swagger to the system. For this case, we are adding Swagger2 dependencies.

 

Adding Api auto-documentation

Once we have the service up and running, we will add Swagger2. As we added the dependencies before , we would just need to specify the api documentation configuration on a @Configuration file:

Once the configuration is set up, we should be able to access the json endpoint for checking the api definition:

http://localhost:8080/v2/api-docs?group=Api

As well as the UI built on top of the api documentation:

http://localhost:8080/swagger-ui.html

Swagger UI. Api autodocumentation for the video service

Swagger UI. Api auto-documentation for the video service

 

Creating the api client

We have the endpoints and the automatic documentation set up. Now it is time to generate the api client based on what we have. For this case we are going to create the api client based on the api definition. The api definition can be accessed through http://localhost:8080/v2/api-docs?group=Api .

For generating the client we are going to use swagger code-gen, a api client generator based on a Open Api definition. There are several ways to create the client as described here, although i recommend checkout the code and create the package that will be used for generating the code (This will allow us to add extra logic for a specific purpose in the future):

Once the project is built, we can create the clients. In order to do that, just stay in the code generator directory and use the target directory to point to the artifact generated (swagger-codegen-cli).

Example for creating Java client

Example for creating Nodejs server

Example for creating Spring mvc client

 

Testing the client

Once the client is generated and with the service up and running, we could start testing the client. In this case, I used the following main method to test the java client generated. The functionality tested is insertion and retrieval of the videos:

When running this on debug mode, we can see the trace of the http calls performed by the client:

 

Contributions

Would you like to contribute to Swagger code gen project? Lot of help is needed and the contributors would like your feedback (was contacted by one of them and they seem proactive related to what the developer community needs 🙂 ). A list of tasks to start contributing can be found here.

 

Summary

  • Writing a REST api for backend developers can be a laborious task. Writing an api client, if the rest api is well defined and designed, should be done easily through http requests (I normally use cURL and Postman for that).
  • Having api clients for the main languages may increase the popularity of your api. The disadvantage is that you may need to maintain them (example: extra logic that is not part of the code generated) so I would recommend doing this step once the api is well defined and almost stage-production ready.
  • Code generation might be good to start but you will have to adapt to how it is written. When the code is generated I normally have a look to the code to see if it is going to be extensible and maintainable.
  • Swagger tools are an interesting resource to have a look, they are really useful for backed and middleware developers.

12 thoughts on “Writing an API client for your Rest API with Swagger code-gen

Leave a Reply

Your email address will not be published. Required fields are marked *