So you have a SpringBoot REST application with a ton of API’s and a postman collection that you use to test out those APIs, but what about documenting those APIs?
I’ve been using postman for a while now and love the documentation feaure that converts the collection into a beautiful html and hosts it on their domain. But most organizations are apprehensive about having their API documentations hosted outside their network available to the public.
To fix this problem I wrote a simple python script that converts a given postman collection to HTML in a format similar to what postman offers. The tool itself can be found here.
But what I really wanted was having the documentation hosted along with the spring boot application so that its easily available for developers & stakeholders alike. I also wanted the documentation auto-generate each time the application builds so that any changes made to the collection are automatically pulled and applied.
How did I do it?
Download the postman-doc-gen executable from here.
Add the postman collection (and the environment file if present) and the executable to the repository under “resources/postman”
Add a new folder under resources and name it “static” which is where the generated HTML documentation will reside
- In the Application class, implement the “WebMvcConfigurer” interface and override the addResourceHandlers and addViewControllers methods.For my application, I wanted the documentation endpoint to be available only on our “dev” environment so I registered the endpoint only if the “currentEnvironment” is “dev2”
- [Optional Step] Most applications have a layer of security that would prevent users from accessing endpoints without some form of authentication. In my case, I wanted the documentation endpoint to be available to everyone on our lower environment. This required changes to the WebSecurityConfig class. I also needed to include the css, js & img folders that would be created by the tool.
- To ensure that the tool runs as part of the build we need to add a build step using the exec-maven-plugin and provide the relevant parameters in the pom.xml
- Finally, run “mvn clean install”. Once the build completes, you should see the documentation files show up inside the “static” folder
Run the application and if all goes well the generated html should be available at the “/documentation” endpoint.
Top comments (0)