spring boot 使用 knife4j，对 springfox 的 swagger 页面进行美化的 demo 示例

1. 描述

一个springboot项目集成 springfox 3.0，使用 knife4j 对 swagger 的 API 接口页面进行美化管理的 demo示例。
提示：knife4j 3.X 和2.X的配置注解使用上有些区别。

环境：

IDE(idea)：2021.3
JDK：1.8
maven：3.8.4
spring boot：2.5.6
springfox：3.0.0
knife4j：3.0.3

2. 结果

• 页面访问：http://localhost:8880/demo/doc.html
  

3. demo

3.0 项目结构

3.1 pom.xml

• 引入 knife4j jar包（knife4j中已经引用了springfox）

<dependencies>
        <!--提供全栈的 web 开发特性，包括 Spring MVC 依赖和 Tomcat 容器-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!--提供好看的swagger界面，Knife4j里面集成了swagger的jar包 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
        </dependency>
        <!-- lombok工具类(编译注解) -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
    </dependencies>

3.2 SpringBootApplication 注解实现启动类

@SpringBootApplication
public class DemoSwaggerKnife4jApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoSwaggerKnife4jApplication.class, args);
        System.out.println("----- http://localhost:8880/demo/ -----");
        System.out.println("----- http://localhost:8880/demo/doc.html -----");
    }
}

3.3 application.yml配置

server:
  port: 8880
  servlet:
    context-path: /demo

3.4 其他代码

• Swagger3Config.java

@Configuration
@EnableOpenApi // swagger版本2用的 @EnableSwagger2
public class Swagger3Config {

    @Bean
    public Docket defaultApi() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("default-api")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.demo.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        String swaggerUrl = "http://localhost:8880/demo/doc.html";
        return new ApiInfoBuilder()
                .title("Swagger UI API")
                .description("Swagger UI API 的一个demo示例")
                .termsOfServiceUrl("http://localhost:8880/demo")
                .contact(new Contact("byrc", swaggerUrl, "best54288@163.com"))
                .license("Apache License Version 2.0")
                .licenseUrl("https://github.com/springfox/springfox/blob/master/LICENSE")
                .version("1.0.0")
                .build();
    }

• UserController .java

@Slf4j
@RestController
@RequestMapping("/user")
@Api(tags = "用户管理")
public class UserController {

    @GetMapping("/{id}")
    @ApiOperation(value = "主键查询", notes = "通过主键查询用户")
    public JsonResponse<User> get(@PathVariable @ApiParam("用户id") Integer id) {
        return JsonResponse.ok(new User(id, "白玉京", 23));
    }

    @DeleteMapping("/{id}")
    @ApiOperation(value = "删除用户", notes = "通过主键删除用户")
    public JsonResponse<String> delete(@PathVariable Integer id) {
        log.info("删除用户 {}", id);
        return JsonResponse.ok();
    }

    @PostMapping
    @ApiOperation(value = "添加用户")
    public JsonResponse<User> post(@RequestBody User user) {
        return JsonResponse.ok(user);
    }
}

4. 资料

• knife4j的官网：https://doc.xiaominfo.com
• springfox github：https://github.com/springfox/springfox
• springfox demo: https://github.com/springfox/springfox-demos/blob/master/boot-swagger

5. 注

• spirng boot 已在父项目引入(父项目pom.xml配置）；
• 部分jar包版本已在父项目管理（如果对应不上，一定、肯定、决定是某些修改，没同步更新文档）。