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

The author introduces Swagger‑Bootstrap‑UI (renamed to Knife4j) as an open‑source UI for Swagger that helps organize and view API documentation, benefiting both backend developers and Android collaborators.

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 to view the generated UI.

The article shows screenshots of the UI and demonstrates testing endpoints with Postman.

4. Common Swagger annotations

The most frequently used annotations are @Api (for grouping) and @ApiOperation (for describing a method). Screenshots illustrate how they appear in the UI.

5. Example 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 = {"用户管理"}, description = "用户管理")
public class UserController {
    @Autowired
    private UsersService usersService;
    @GetMapping("/list")
    @ApiOperation(value = "用户列表")
    public List
list() {
        return usersService.list();
    }
}

6. Additional resources

Links to other Swagger integration tutorials are provided for deeper exploration.

7. Potential issues

Common problems include the documentation page being blocked by security filters (e.g., Shiro or Spring Security) or the UI not scanning any controllers due to incorrect package configuration. Screenshots illustrate these scenarios and suggest checking the official documentation or raising an issue on the project's GitHub page.