Hosting API documentation with Postman & SpringBoot
Tags: postman, springboot, api, documentation
Published: 2023-06-19 06:39:04

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](https://github.com/karthiks3000/postman-doc-gen).

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](https://github.com/karthiks3000/postman-doc-gen/releases).

- 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

![The resources directory](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/uxqda801pp5pqq7cm5v0.png)

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

![The SpringBoot Application class](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/szh13au5reba9xuhcvdc.png)

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

![The configure method](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ac1y3fcdx97m30rykhhb.png)

- 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

![The pom.xml plugin](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/0fg9bfl4iqy5pjzoa1g4.png)

- Finally, run “mvn clean install”. Once the build completes, you should see the documentation files show up inside the “static” folder

![The static folder after the build completes](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4q67xq66tv01ve6ja8t2.png)

Run the application and if all goes well the generated html should be available at the “/documentation” endpoint.