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
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.
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.