Open API Specifications with your API REST Spring Boot

Bruna Pereira
Feb 12, 2020 · 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.

Interested in working with us? We’re always looking for people passionate about technology to join our crew! You can check out our openings here.

Creditas Tech

Our technologies, innovations, digital product management…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

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