Open API Specifications with your API REST Spring Boot

Bruna Pereira
Feb 12 · 2 min read

When we are developing an API with Spring Boot, by using Springfox’s Swagger-UI we no longer need to manually write the specifications of our endpoints and everything is generated with very few configuration lines.

Thus, it’s common to conduct some more in-depth planning prior to the development of REST APIs; whether it be to test the hypothesis, arrange contact between dependencies, or any other reason.

This is when I found myself needing to make two documentation versions available in my API. The first is the automatically generated documentation, which is really useful for actual testing since it tests endpoints. The second is the complete documentation, which was written beforehand and sets a foundation for developers, facilitating conversations about the near future.

I already have Swagger configured in my application, and I’m using version 2.9.2 of swagger2 and swagger-ui.

1. Create the specification

SwaggerHub is a platform with various functionalities for the creation of OpenAPIs. It also has a limited free version that can be used, but if you want something simpler you can also use https://editor.swagger.io/ or similar tools.

Once finalized, export to a JSON file and save it to src/main/resources/public.

2. Add the new file to Swagger UI

To configure a new file, add the following configuration class to your application:

Ensure that on line 11 you have the name of the JSON file that is inside the public or static directory in resources.

3. Test

When you open swagger’s url, you should be able to choose the specification you want to see in the top right corner. If everything is correctly configured, you should see the default option, which was automatically generated, and another option, which is the file you just created, as depicted below.

One last tip: make sure that in the documentation description, at the top of the page, you can easily identify which version is currently implemented, so that people don’t get confused.

Creditas Tech

Our technologies, innovations, digital product management, culture, and much more!

Bruna Pereira

Written by

Software Developer. I write code that humans can understand.

Creditas Tech

Our technologies, innovations, digital product management, culture, and much more!

More From Medium

More on Engineering from Creditas Tech

More on Engineering from Creditas Tech

Don’t be a developer who only knows how to write code

More on Engineering from Creditas Tech

More on Engineering from Creditas Tech

More on Engineering from Creditas Tech

Feature Flags using Kotlin + Spring Boot

16

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade