Creating API specs and generating skeleton project from it

Owned by Shashwat Mishra
Last updated: Jul 31, 2022
2 min read

The first step to develop any microservice starts at preparing a Swagger documentation which details out all the APIs that the service is going to expose which the clients can consume.

Swagger is a utility which allows you to describe the structure of your APIs so that machines can read them. Readers can go through the following link to understand what swagger is in depth - What is Swagger?

Now comes the big question, why swagger?

There are a couple of reasons as to why we emphasize the creation of swagger contracts at the start of creating any microservices.

  1. Allows us to generate REST API documentation and interact with them ( Using Swagger UI ). Interaction with the APIs helps clients to understand so as to how the APIs respond to various parameters. 

  2. Swagger codegen tool and SwaggerHub can be used to generate server stubs and client SDKs using these swagger contracts (fancy way of saying it implements all the humdrum code that is required to get the API skeleton ready, right from the controller layer to the models). This in turn allows the developers to focus on the business logic rather than worrying about creating model classes and controller code.

 

The following tutorial can be used for the creation of swagger contracts - OpenAPI 3.0 Tutorial| Swagger Tutorial For Beginners | Design REST API Using Swagger Editor 

For generating projects from swagger contracts, we use our customized swagger codegen jar.

We have to download the jar from the following link - CODEGEN JAR LINK

Following is the generic command to create API skeleton for any swagger contract:

java -jar codegen-1.0-SNAPSHOT-jar-with-dependencies.jar -l -t -u {CONTRACT_PATH } -a ARTIFACT_ID -b BASE_FOLDER

 

For this guide, the following should be the sequence to generate API skeleton using codegen jar:

  1. Go to the folder where you have downloaded the codegen jar.

  2. Execute the following command:

java -jar codegen-1.0-SNAPSHOT-jar-with-dependencies.jar -l -t -u https://raw.githubusercontent.com/egovernments/DIGIT-OSS/DIGIT-DEVELOPER-TUTORIAL/municipal-services/docs/voter-registration.yml -a voter-registration -b digit

OR, if you have created the swagger contract file locally, use the following command to generate the skeleton code -

java -jar codegen-1.0-SNAPSHOT-jar-with-dependencies.jar -l -t -u file:///C:/Users/shash/Desktop/New/contract.yml -a voter-registration -b digit

  1. Update the spring-boot-starter-parent to 2.2.6-RELEASE

(After updating spring boot version do maven update)

  1. Put a slash in front of

server.contextPath and add this property to application.properties file which helps requests handlers to serve requests -

server.contextPath=/voter-registration server.servlet.context-path=/voter-registration

  1. Add these external dependencies to pom.xml:

<dependency>    <groupId>org.flywaydb</groupId>    <artifactId>flyway-core</artifactId> </dependency> <dependency>    <groupId>org.postgresql</groupId>    <artifactId>postgresql</artifactId>    <version>42.2.2.jre7</version> </dependency>