Step by step OpenAPI Swagger setup

We’ll be using the following setups for this walkthrough

  • Springboot
  • Kotlin
  • Maven
  • OpenApiTool
  • Swagger-Codegen
  • Java 8
  • Intellij

Project setup

Let’s setup the Springboot code base first at https://start.spring.io/

Download the generated project and load it into Intellij

Write your own YAML Contract

You can use SwaggerHub https://swagger.io/tools/swaggerhub/ to write the contract. The online editor provides intellisense and error checking. You can also see the contract UI real time as you construct the contract. For our demo we’ll write up a basic contract.

I’ll use the below yaml for this demo.

Copy the above yaml and save it as sampleApi.yaml and place it in the below dir within your project:

/src/main/resources/spec/sampleApi.yaml

Generate Code Stub for API Producer

Add the below maven dependencies

Add the below plugin

Make sure that the inputSpec path is where you’re putting your yaml contract.

Run the below command

When the project is compiled, you should be able to see the generated code stubs just like below

Let’s take a look at the code stubs generated.

If we look into the InventoryApi and InventoryApiController classes, we see that the code-gen helped to generate your typical boiler plate code for a controller. The actual operation for the Api is in the InventoryApiDelegate. Currently in the InventoryApiDelegate interface it’s throwing a 501 NOT IMPLEMENTED as a default implmentation.

As the producer of this API all you need to do is just to inherit this interface and implement the methods as you see in the example below.

Now if you have the above service implementation setup, we’ll try calling the API to see what we will get.

Let’s call the one we implemented — 200

curl — location — request GET ‘http://localhost:8080/v1/inventory?searchString=&skip=&limit=‘

Let’s call the one we didn’t implement — 501

curl — location — request POST ‘http://localhost:8080/v1/inventory'

Now your APIs are ready to roll.

Generate Code Stub API Consumer

Let’s write a contract for a service that already exists for the consumer portion.

Add the below maven dependencies

Add the below plugin

Make sure that the inputSpec path is where you’re putting your yaml contract

Run the below command

When the project is compiled, you should be able to see the generated code stubs just like below

In order to use this API you’ll need to add a config before you can autowire the api class

We’ll create a simple controller to invoke the api class

Now we’ll try to call the test API from postman to see the result

And this is how you can call an API through the contract generated code stubs.

Can I customize the generated code stubs?

Yes! Whether you’re using the openapitool or swagger code gen or any other open api code stub generation dependency you should be able to customize the code that are generated. Some like to generate all the annotations for the controller and override the code in the controller instead and others like to completely ignore the controller layer and work in the service layer.

Refer to the below documentations when customizing:

Github Repo

Producer code: master branch

Consumer code: swagger-code-gen-version branch

Just another developer who's into lazy tools that can make my life easier, and hopefully yours too.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store