Grigor Avagyan is an Information Technologies Engineer. He has 12 years of experience in automation engineering, QA and development. Grigor's expertise includes manual and automated testing, continuous integration and Atlassian products.

Become a JMeter and Continuous Testing Pro

Start Learning

Test Your Website Performance NOW!

arrowPlease enter a URL with http(s)
Assert:is found in response
Aug 02 2017

How to Automatically Document API Endpoints via Swagger

Documentation of any code is usually the most boring part, and as a developer you probably always look for ways to automate it. One of the ways to do so is by creating your own automation. However, nowadays we can enjoy the luxury of a fast growing IT industry that brings lots of tools and frameworks to the table.


One of these tools is Swagger, and in this article we will learn how to automate documentation of API Endpoints via Swagger.


The complete source can be found here. This article will show code fragments.


The environment we will auto document with Swagger will be Java and Spring Boot API, together with the Gradle build tool. As usual my articles are related to the JAVA development environment.


1. First, like in any library, we need to add all the dependencies.


For Maven users:




For Gradle users:

compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.7.0'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.7.0'


2. The next step is to enable Swagger for full Spring Boot Application. This can be done in the following way:

public class BlazeMeterApi {
   public static void main(String[] args) {, args);

   public Docket api() {
       return new Docket(DocumentationType.SWAGGER_2).select()

   ApiInfo apiInfo() {
       final ApiInfoBuilder builder = new ApiInfoBuilder();
       builder.title("BlazeMeter Spring Boot API").version("1.0").license("(C) Copyright BlazeMeter")
               .description("List of all endpoints used in API");


Let’s understand the code. The @EnableSwagger2 annotation is telling the application and Swagger that this is our starting point and application. Then we have 2 @Bean annotated methods, or just beans.


The first (api) is a configuration for what to cover, where to look and where the documentation will be living (main path - / ). The second one (apiInfo) is the informational part of documentation: title, version, license, description, etc.


3. The next step will be to to create a main controller for Swagger, for opening Swagger UI via redirection to swagger-ui.html:@Controller


import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;

public class RootController {
   @RequestMapping(method = RequestMethod.GET)
   public String swaggerUi() {
       return "redirect:/swagger-ui.html";


This code is quite simple: it is creating a GET request holder controller that is redirecting GET requests from the application / to the /swagger-ui.html, and that’s it.


4. The next and final step is to annotate API Controllers with @Api and @ApiOperation:


@RequestMapping(value = VERSION + ARRIVAL)
@Api(value = VERSION + ARRIVAL)
public class ArrivalController {

   private ArrivalRepository arrivalRepository;

   @ApiOperation(value = "Get all arrivals")
   @RequestMapping(value = "all", method = GET)
   public List<Arrival> getAllArrivals() {
       return arrivalRepository.findAll();

   @ApiOperation(value = "Get arrival by ID")
   @RequestMapping(value = "{id}", method = GET)
   public Arrival getArrivalById(@PathVariable(value = "id") int id) {
       return arrivalRepository.findAllById(id);


The @Api annotation should be used on top of the controller class and have a value of high level mapping, if there is one (it’s best practice to have one).


The @ApiOperation annotation can be on any method level that you want to cover with Swagger, and it may have value that is a short description of the endpoint.


That’s all folks. After executing the project we will have fully documented API endpoints. It will look like this:


automated api documentation with swagger


This is Swagger’s main page, containing all the annotated API endpoints in the list, grouped by controllers.


And after expanding a few of endpoints to check more details:


swagger, api testing, documentation


That’s it! You can now save time and effort by automatically documenting your API endpoints with Swagger.


Looking to automate your API tests? Get your API Testing started with BlazeMeter.


Click here to subscribe to our newsletter.

arrowPlease enter a URL with http(s)

Interested in writing for our Blog?Send us a pitch!