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

The author recounts using Swagger for API documentation at a startup and later discovering Swagger‑Bootstrap‑UI, which was later renamed Knife4j and expanded from monolithic to micro‑service scenarios.

To add the UI, include the following 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>

Next, create a configuration class annotated with @Configuration , @EnableSwagger2 and @EnableSwaggerBootstrapUI . The class defines a Docket bean that scans the controller package and sets API metadata via ApiInfoBuilder :

@Configuration
@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();
    }
}

After starting the application without errors, the documentation is accessible at http:// host : port /doc.html . The UI shows grouped APIs and can be tested with tools like PostMan.

Common Swagger annotations such as @Api (for grouping) and @ApiOperation (for method description) work unchanged with Knife4j. Example controller:

@RestController
@RequestMapping("/user")
@Api(tags = {"用户管理"}, description = "用户管理")
public class UserController {
    @Autowired
    private UsersService usersService;
    @GetMapping("/list")
    @ApiOperation(value = "用户列表")
    public List
list() {
        return usersService.list();
    }
}

Potential issues include the documentation page being blocked by security filters (e.g., Shiro or Spring Security) or the scanner not finding controllers due to incorrect base‑package configuration. The article advises checking the configuration and consulting the official documentation for a FAQ.

Additional resources and links to the GitHub repository and Chinese documentation are provided for further reference.