Integrating Swagger‑Bootstrap‑UI (Knife4j) into a Spring Boot Project

In this guide the author shares the experience of replacing the default Swagger UI with the open‑source Swagger‑Bootstrap‑UI (renamed to Knife4j) to generate and organize API documentation for a Spring Boot backend, which is also useful for Android developers during integration testing.

1. Add Maven dependencies

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

2. Add configuration class

package com.blog.tutorial.config;
import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfiguration {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.blog.tutorial.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger-bootstrap-ui RESTful APIs")
                .description("swagger-bootstrap-ui")
                .termsOfServiceUrl("http://localhost:5050/")
                .contact("[email protected]")
                .version("1.0")
                .build();
    }
}

3. Start the project

Run the Spring Boot application without errors and open http:// ip : port /doc.html in a browser to view the generated documentation.

The resulting UI looks like the screenshots below:

Testing the APIs with tools such as PostMan produces the same visual results.

4. Common annotations

Swagger‑Bootstrap‑UI supports the same annotations as standard Swagger. The two most frequently used are @Api (to describe a controller or group of endpoints) and @ApiOperation (to describe a single method). Screenshots of their effects are shown below.

These annotations provide a clear classification and description for each API endpoint.

5. Sample controller code

package com.blog.tutorial.controller;
import com.blog.tutorial.entity.Users;
import com.blog.tutorial.service.UsersService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;

@RequestMapping("/user")
@Api(tags = {"User Management"}, description = "User Management")
public class UserController {
    @Autowired
    private UsersService usersService;
    @GetMapping("/list")
    @ApiOperation(value = "User List")
    public List
list() {
        return usersService.list();
    }
}

6. Possible issues

1) The documentation page returns a blank screen – usually caused by security filters (Shiro, Spring Security) or misconfiguration.

2) The page loads but no endpoints are scanned – often due to an incorrect base‑package in the configuration; ensure it points to the controller package.

For other problems, consult the official Knife4j documentation, which includes a FAQ section, or open an issue on the project's GitHub repository with detailed description and relevant code.