How To Document REST API

If you are working on a REST API for your project and you need to document it so that you can share API documentation with other team members or external to your team developers, there at least a couple of ways to do it:

  1. You can either open a new Google Document and start writing API documentation from scratch or,
  2. You can use tools like Swagger to let it automatically generate an interactive API which other developers can use to learn what are the Web Service Endpoints available to them, what requests parameters they need to pass, what response to expect and etc.

Add Swagger to Your REST API Project

To document RESTful Web Services I create, I always use Swagger and in one of my earlier blog posts I have share how to add Swagger to your RESTful Web Services project built with Spring Boot and how to make it generate an Interactive API. Have a look it this blog post:

How to Add Swagger to a Spring Boot REST API Project

Swagger and Spring Security

If your RESTful Web Service project uses Spring Security then you will need to make a little configuration to make your Swagger work. Have a look at this blog post on how to configure Spring Security to make Swagger URL paths available:

Swagger and Spring Security

I hope this very short blog post was helpful for you.

If you are interested in learning more about Swagger, have a look at the below video courses. I personally enjoy learning by following a well prepared step by step video lessons.