---

API文档集成与增强

Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案

集成open api

官网文档: springdoc-openapi

1. 依赖导入

<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-ui</artifactId>
	<version>1.6.11</version>
</dependency>

2. 配置文件设置

# open api配置
springdoc:
  packages-to-scan: com.example.swagger3knife4j.controller
  swagger-ui:
    enabled: true
  api-docs:
    enabled: true

3. 文档设置

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI api() {
        return new OpenAPI().info(new Info().title("文档标题")
                .description("文档描述")
                .version("v1.0.0"));
    }
}

到此配置就完成了，接下来便是使用open api的规范来生成对应的API文档

---

open api使用方法

1. 首先通过@Tag给文档添加注释，通过@Operation给每个接口添加文档注释

@Tag(name = "用户接口")
@RestController
@RequestMapping(PRIVATE_PATH + "/user")
public class UserController {

    @GetMapping("/getOneUser")
    @Operation(summary = "随机获取一个用户")
    public User getOneUser() {
        return new User("姓名", "13899999999");
    }
}

2. 通过@Schema给自定义对象（入参和返回相同）添加文档注释

@Data
@AllArgsConstructor
@Schema(description = "用户信息")
public class User {

    @Schema(description = "姓名")
    private String name;

    @Schema(description = "电话")
    private String phone;
}

3. 访问地址：http://localhost:8888/swagger-ui/index.html

到此一个简单的接口文档便生成了，下面是效果图：

实体注释：

如上就是open api3的全部设置，它是基于swagger-ui设计的，因此界面和swagger没什么区别。

不过open api3的注解与swagger2完全不同，下面是两者注解的对应关系，方便swagger2的使用者快速开发。

---

open api与swagger注解方法的对应关系

open api的注解与swagger的有很大区别，open api的写法更为简单易懂，在实际使用时也不会像swagger的注解那样让人迷惑。

如下是两者注解的对应关系：

官网链接: 官网链接

下面介绍一款swagger的增强框架—knife4j，它的界面美观性因人而异，但是在使用体验上绝对甩swagger界面好多倍。废话不多说，直接将knife4j撸进来。

---

集成knife4j

官网文档: Knife4j

1. 依赖导入

<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-springdoc-ui</artifactId>
	<version>3.0.3</version>
</dependency>

ok，配置好之后，直接访问Knife4j的界面试试：http://localhost:8888/doc.html

Swagger和Knife4j的访问地址不同，但是都可以修改。

• http://localhost:8888/swagger-ui/index.html
• http://localhost:8888/doc.html

这时，Knife4j的访问界面都是一片空白的，不过不用慌，因为我们还需要为Knife4j添加相应的文件目录

2. 在此前为的配置文件OpenApiConfig中，添加Knife4j的文档设置，这里所有前缀为“PRIVATE_PATH”的接口，都用过“基础接口”这个目录来访问

@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("基础接口")
            .pathsToMatch(PRIVATE_PATH + "/**")
            .build();
}

此时重启，Knife4j的页面内容如下：

3. 相关功能点介绍

• 主页：展示了一些接口的统计信息
• SwaggerModels：展示了所有的传输对象
• 文档管理：提供全局参数设置（如在请求头添加token登）、离线文档下载（Knife4j提供导出4种格式的离线文档(Html/Markdown/Word/OpenAPI)）、以及一些其它个性化设置。
• “用户接口”：这些目录就是我们生成好的接口文档了。

---

API文档的常用内容

为@PathVariable的参数添加文档注释

添加@Parameter参数就行

    @GetMapping("/getName/{userName}")
    @Operation(summary = "获取用户名")
    public String getName(@Parameter(required = true, name = "userName", description = "用户名")
                                 @PathVariable("userName") String userName) {
        return userName;
    }

接口分组

接口分组的方式很简单，即在文件中设置其它分组，同时设置不同的请求路径即可

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("公共接口")
                .pathsToMatch(PUBLIC_PATH + "/**")
                .build();
    }
    @Bean
    public GroupedOpenApi privateApi() {
        return GroupedOpenApi.builder()
                .group("私有接口")
                .pathsToMatch(PRIVATE_PATH + "/**")
                .build();
    }

设置全局请求头（token）

如果需要为某个分组添加必填字段的话，可以通过如下方式实现：

    @Bean
    public GroupedOpenApi tokenApi(OperationCustomizer operationCustomizer) {
        return GroupedOpenApi.builder()
                .group("鉴权")
                .pathsToMatch(PRIVATE_PATH + "/**")
                .addOperationCustomizer(operationCustomizer)
                .build();
    }

    @Bean
    public OperationCustomizer operationCustomizer() {
        return (operation, handlerMethod) -> operation.addParametersItem(
                new Parameter()
                        .in("header")
                        .required(true)
                        .description("token 验证")
                        .name("token"));
    }

此时该分组的接口，必须传递该字段（当然这只是一种规范，实际请求时还需要自行加上token登必传字段的校验）

在使用文档时，可以在全局参数设置中添加改参数，避免每个接口都要再填一遍（确定后刷新生效）。

在特定环境屏蔽API文档

开发和测试环境需要文档，但是上线之后，就必须把这些文档给屏蔽调。

比如生成环境prod，只需要在生成环境的yml文件中需改如下springdoc的配置即可：

springdoc:
  packages-to-scan: com.example.swagger3knife4j.controller
  swagger-ui:
    enabled: false
  api-docs:
    enabled: false

---

源码地址

源码: github仓库地址