You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
348 lines
17 KiB
348 lines
17 KiB
1 month ago
|
# Knife4j API文档配置
|
||
|
|
|
||
|
|
<cite>
|
||
|
|
**本文档引用的文件**
|
||
|
|
- [Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)
|
||
|
|
- [application.yml](file://crm-app/src/main/resources/application.yml)
|
||
|
|
- [application.yml](file://crm-auth/src/main/resources/application.yml)
|
||
|
|
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
|
||
|
|
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
|
||
|
|
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
|
||
|
|
- [BaseParam.java](file://crm-base/src/main/java/com/crm/base/domain/param/BaseParam.java)
|
||
|
|
- [BaseDTO.java](file://crm-base/src/main/java/com/crm/base/domain/dto/BaseDTO.java)
|
||
|
|
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
|
||
|
|
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
|
||
|
|
</cite>
|
||
|
|
|
||
|
|
## 目录
|
||
|
|
1. [简介](#简介)
|
||
|
|
2. [项目结构](#项目结构)
|
||
|
|
3. [核心组件](#核心组件)
|
||
|
|
4. [架构总览](#架构总览)
|
||
|
|
5. [详细组件分析](#详细组件分析)
|
||
|
|
6. [依赖关系分析](#依赖关系分析)
|
||
|
|
7. [性能考虑](#性能考虑)
|
||
|
|
8. [故障排查指南](#故障排查指南)
|
||
|
|
9. [结论](#结论)
|
||
|
|
10. [附录](#附录)
|
||
|
|
|
||
|
|
## 简介
|
||
|
|
本文件面向Knife4j API文档配置模块，围绕Swagger集成、文档分组管理、认证鉴权集成、自定义美化、多环境配置与生产禁用策略、接口权限控制、参数校验提示、错误码说明、文档导出、在线调试与版本管理等主题进行系统化说明。目标是帮助开发者快速搭建高质量、可维护的API文档体系，并在不同环境下灵活启用或关闭文档能力。
|
||
|
|
|
||
|
|
## 项目结构
|
||
|
|
本项目采用模块化组织，Knife4j相关配置位于基础模块中，统一对外提供文档能力；认证与安全配置位于认证模块；应用入口与全局配置位于应用模块。
|
||
|
|
|
||
|
|
```mermaid
|
||
|
|
graph TB
|
||
|
|
subgraph "应用层"
|
||
|
|
APP["应用启动<br/>CrmAppApplication"]
|
||
|
|
APP_YML_APP["应用配置<br/>application.yml"]
|
||
|
|
end
|
||
|
|
subgraph "基础模块"
|
||
|
|
BASE_KNIFE4J["Knife4j配置<br/>Knife4jConfig"]
|
||
|
|
BASE_RESULT["统一结果封装<br/>Result / ResultCodeEnum"]
|
||
|
|
BASE_PARAM["通用参数基类<br/>BaseParam / BaseDTO"]
|
||
|
|
BASE_EX["全局异常处理<br/>GlobalExceptionHandlerAdvice"]
|
||
|
|
end
|
||
|
|
subgraph "认证模块"
|
||
|
|
AUTH_SEC["安全配置<br/>SecurityConfig"]
|
||
|
|
AUTH_JWT["JWT过滤器<br/>JwtAuthenticationFilter"]
|
||
|
|
AUTH_YML["认证配置<br/>application.yml"]
|
||
|
|
end
|
||
|
|
APP --> BASE_KNIFE4J
|
||
|
|
APP --> AUTH_SEC
|
||
|
|
AUTH_SEC --> AUTH_JWT
|
||
|
|
BASE_KNIFE4J --> BASE_RESULT
|
||
|
|
BASE_KNIFE4J --> BASE_PARAM
|
||
|
|
BASE_KNIFE4J --> BASE_EX
|
||
|
|
APP_YML_APP -. 环境变量 .-> BASE_KNIFE4J
|
||
|
|
AUTH_YML -. 环境变量 .-> AUTH_SEC
|
||
|
|
```
|
||
|
|
|
||
|
|
图表来源
|
||
|
|
- [Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)
|
||
|
|
- [application.yml](file://crm-app/src/main/resources/application.yml)
|
||
|
|
- [application.yml](file://crm-auth/src/main/resources/application.yml)
|
||
|
|
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
|
||
|
|
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
|
||
|
|
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
|
||
|
|
- [BaseParam.java](file://crm-base/src/main/java/com/crm/base/domain/param/BaseParam.java)
|
||
|
|
- [BaseDTO.java](file://crm-base/src/main/java/com/crm/base/domain/dto/BaseDTO.java)
|
||
|
|
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
|
||
|
|
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)
|
||
|
|
- [application.yml](file://crm-app/src/main/resources/application.yml)
|
||
|
|
- [application.yml](file://crm-auth/src/main/resources/application.yml)
|
||
|
|
|
||
|
|
## 核心组件
|
||
|
|
- Knife4j配置：集中定义Swagger扫描包、分组、标题、版本、许可信息、UI增强等。
|
||
|
|
- 统一结果与错误码：为接口返回结构与错误码枚举提供规范，便于文档生成与展示。
|
||
|
|
- 通用参数与DTO：通过注解与基类约定，提升参数校验与文档描述的一致性。
|
||
|
|
- 全局异常处理：将业务异常转换为统一的JSON响应，确保文档中的错误示例稳定。
|
||
|
|
- 安全配置与JWT过滤：与Knife4j集成时，需对文档端点放行并支持在“尝试运行”中携带Token。
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)
|
||
|
|
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
|
||
|
|
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
|
||
|
|
- [BaseParam.java](file://crm-base/src/main/java/com/crm/base/domain/param/BaseParam.java)
|
||
|
|
- [BaseDTO.java](file://crm-base/src/main/java/com/crm/base/domain/dto/BaseDTO.java)
|
||
|
|
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
|
||
|
|
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
|
||
|
|
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
|
||
|
|
|
||
|
|
## 架构总览
|
||
|
|
下图展示了Knife4j在系统中的位置与交互：应用启动加载Knife4j配置，SpringDoc/Swagger扫描控制器生成OpenAPI元数据，Knife4j UI负责渲染与增强；认证模块的安全配置对文档端点进行放行，同时允许在调试时注入认证头。
|
||
|
|
|
||
|
|
```mermaid
|
||
|
|
sequenceDiagram
|
||
|
|
participant Dev as "开发者浏览器"
|
||
|
|
participant App as "应用启动"
|
||
|
|
participant K4j as "Knife4j配置"
|
||
|
|
participant Sdoc as "SpringDoc/OpenAPI"
|
||
|
|
participant Sec as "安全配置"
|
||
|
|
participant Jwt as "JWT过滤器"
|
||
|
|
Dev->>App : 访问 /doc.html
|
||
|
|
App->>K4j : 初始化Knife4j
|
||
|
|
K4j->>Sdoc : 注册扫描包与分组
|
||
|
|
Dev->>Sec : 请求 /v3/api-docs
|
||
|
|
Sec-->>Dev : 放行文档端点
|
||
|
|
Dev->>Jwt : 携带Authorization(可选)
|
||
|
|
Jwt-->>Dev : 透传至后端服务
|
||
|
|
Sdoc-->>Dev : 返回OpenAPI JSON
|
||
|
|
K4j-->>Dev : 渲染增强UI
|
||
|
|
```
|
||
|
|
|
||
|
|
图表来源
|
||
|
|
- [Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)
|
||
|
|
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
|
||
|
|
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
|
||
|
|
|
||
|
|
## 详细组件分析
|
||
|
|
|
||
|
|
### Knife4j配置（Swagger集成与分组）
|
||
|
|
- 作用：集中配置Swagger扫描范围、分组规则、文档元信息（标题、版本、许可）、UI增强项（如排序、标签分组）。
|
||
|
|
- 关键点：
|
||
|
|
- 扫描包：限定Controller所在包，避免无关类被扫描。
|
||
|
|
- 分组：按业务域划分（如认证、系统、文件），便于导航。
|
||
|
|
- 元信息：设置文档标题、版本、许可证、作者等。
|
||
|
|
- UI增强：开启排序、标签分组、隐藏无用端点等。
|
||
|
|
- 多环境：通过配置文件开关控制是否启用Knife4j。
|
||
|
|
|
||
|
|
```mermaid
|
||
|
|
flowchart TD
|
||
|
|
Start(["应用启动"]) --> LoadCfg["加载Knife4j配置"]
|
||
|
|
LoadCfg --> ScanPkgs["扫描指定包路径"]
|
||
|
|
ScanPkgs --> BuildGroups["构建分组与标签"]
|
||
|
|
BuildGroups --> ApplyMeta["设置文档元信息"]
|
||
|
|
ApplyMeta --> EnableUI["启用UI增强"]
|
||
|
|
EnableUI --> Ready(["文档可用"])
|
||
|
|
```
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)
|
||
|
|
|
||
|
|
### 统一结果与错误码（错误码说明）
|
||
|
|
- 作用：为所有接口返回统一结构，配合错误码枚举，使文档中的响应示例清晰一致。
|
||
|
|
- 关键点：
|
||
|
|
- 统一响应体：包含状态码、消息、数据等字段。
|
||
|
|
- 错误码枚举：集中定义业务错误码与描述，便于文档展示与前端解析。
|
||
|
|
- 异常转响应：全局异常处理器将异常转为统一响应，保证文档示例稳定。
|
||
|
|
|
||
|
|
```mermaid
|
||
|
|
classDiagram
|
||
|
|
class Result {
|
||
|
|
+code : int
|
||
|
|
+message : string
|
||
|
|
+data : object
|
||
|
|
}
|
||
|
|
class ResultCodeEnum {
|
||
|
|
+SUCCESS : int
|
||
|
|
+ERROR : int
|
||
|
|
+AUTH_FAIL : int
|
||
|
|
+PARAM_ERROR : int
|
||
|
|
}
|
||
|
|
class GlobalExceptionHandlerAdvice {
|
||
|
|
+handleException(e) Response
|
||
|
|
}
|
||
|
|
Result <.. ResultCodeEnum : "使用"
|
||
|
|
GlobalExceptionHandlerAdvice --> Result : "构造响应"
|
||
|
|
```
|
||
|
|
|
||
|
|
图表来源
|
||
|
|
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
|
||
|
|
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
|
||
|
|
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
|
||
|
|
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
|
||
|
|
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
|
||
|
|
|
||
|
|
### 通用参数与DTO（参数校验提示）
|
||
|
|
- 作用：通过注解与基类约束，统一参数校验与文档描述，减少重复代码。
|
||
|
|
- 关键点：
|
||
|
|
- 基类字段：如分页、排序、时间范围等常用字段集中定义。
|
||
|
|
- 校验注解：必填、长度、格式等校验注解用于参数校验与文档提示。
|
||
|
|
- DTO设计：输入输出分离，明确字段含义与示例。
|
||
|
|
|
||
|
|
```mermaid
|
||
|
|
classDiagram
|
||
|
|
class BaseParam {
|
||
|
|
+page : int
|
||
|
|
+size : int
|
||
|
|
+sortField : string
|
||
|
|
+sortOrder : string
|
||
|
|
}
|
||
|
|
class BaseDTO {
|
||
|
|
+id : long
|
||
|
|
+createTime : datetime
|
||
|
|
+updateTime : datetime
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
图表来源
|
||
|
|
- [BaseParam.java](file://crm-base/src/main/java/com/crm/base/domain/param/BaseParam.java)
|
||
|
|
- [BaseDTO.java](file://crm-base/src/main/java/com/crm/base/domain/dto/BaseDTO.java)
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [BaseParam.java](file://crm-base/src/main/java/com/crm/base/domain/param/BaseParam.java)
|
||
|
|
- [BaseDTO.java](file://crm-base/src/main/java/com/crm/base/domain/dto/BaseDTO.java)
|
||
|
|
|
||
|
|
### 安全配置与JWT集成（认证鉴权集成）
|
||
|
|
- 作用：在启用安全框架的前提下，放行Knife4j与OpenAPI端点，同时支持在“尝试运行”中注入认证头。
|
||
|
|
- 关键点：
|
||
|
|
- 放行路径：/doc.html、/swagger-resources、/v3/api-docs等。
|
||
|
|
- Token注入：在请求头中携带Authorization，供在线调试使用。
|
||
|
|
- 过滤器链：JWT过滤器解析Token并填充上下文，不影响文档端点。
|
||
|
|
|
||
|
|
```mermaid
|
||
|
|
sequenceDiagram
|
||
|
|
participant Browser as "浏览器"
|
||
|
|
participant Sec as "SecurityConfig"
|
||
|
|
participant Jwt as "JwtAuthenticationFilter"
|
||
|
|
participant Api as "业务接口"
|
||
|
|
Browser->>Sec : 访问 /doc.html
|
||
|
|
Sec-->>Browser : 放行
|
||
|
|
Browser->>Sec : 调用业务接口
|
||
|
|
Sec->>Jwt : 检查Authorization
|
||
|
|
Jwt-->>Sec : 解析成功/失败
|
||
|
|
Sec->>Api : 放行到控制器
|
||
|
|
Api-->>Browser : 返回结果
|
||
|
|
```
|
||
|
|
|
||
|
|
图表来源
|
||
|
|
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
|
||
|
|
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
|
||
|
|
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
|
||
|
|
|
||
|
|
### 多环境与生产禁用策略
|
||
|
|
- 开发/测试环境：默认启用Knife4j，便于联调与自测。
|
||
|
|
- 生产环境：通过配置开关禁用Knife4j与OpenAPI端点，降低安全风险。
|
||
|
|
- 建议：
|
||
|
|
- 使用配置文件区分环境（如dev/test/prod）。
|
||
|
|
- 在生产环境中关闭文档UI与OpenAPI JSON暴露。
|
||
|
|
- 如需审计，可通过白名单IP限制访问。
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [application.yml](file://crm-app/src/main/resources/application.yml)
|
||
|
|
- [application.yml](file://crm-auth/src/main/resources/application.yml)
|
||
|
|
|
||
|
|
### 自定义美化与分组管理
|
||
|
|
- 分组管理：按业务域划分文档分组，提升可读性与导航效率。
|
||
|
|
- 自定义美化：通过Knife4j增强项调整UI样式、排序规则、标签分组等。
|
||
|
|
- 最佳实践：
|
||
|
|
- 为每个Controller添加清晰的分组与标签。
|
||
|
|
- 使用注解完善字段描述、示例值与校验规则。
|
||
|
|
- 在文档中补充使用说明与注意事项。
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)
|
||
|
|
|
||
|
|
### 接口权限控制与参数校验提示
|
||
|
|
- 权限控制：结合安全框架，对需要鉴权的接口进行保护；文档端点保持开放。
|
||
|
|
- 参数校验：使用校验注解实现服务端校验，同时在文档中显示必填与格式要求。
|
||
|
|
- 错误码说明：统一错误码枚举与响应体，确保文档中的错误示例与实际一致。
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
|
||
|
|
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
|
||
|
|
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
|
||
|
|
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
|
||
|
|
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
|
||
|
|
|
||
|
|
### 文档导出、在线调试与版本管理
|
||
|
|
- 文档导出：支持导出OpenAPI JSON/YAML，便于第三方集成与离线查看。
|
||
|
|
- 在线调试：在Knife4j界面直接发起请求，支持携带认证头与请求体。
|
||
|
|
- 版本管理：通过版本号与分组区分不同版本的API，逐步迁移与兼容。
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)
|
||
|
|
|
||
|
|
## 依赖关系分析
|
||
|
|
Knife4j依赖SpringDoc/OpenAPI生成元数据，并与安全框架协作以放行文档端点；统一结果与异常处理确保文档示例一致性。
|
||
|
|
|
||
|
|
```mermaid
|
||
|
|
graph LR
|
||
|
|
K4j["Knife4jConfig"] --> OpenAPI["OpenAPI/SpringDoc"]
|
||
|
|
K4j --> UI["Knife4j UI"]
|
||
|
|
Sec["SecurityConfig"] --> K4j
|
||
|
|
Jwt["JwtAuthenticationFilter"] --> Sec
|
||
|
|
K4j --> Result["Result/ResultCodeEnum"]
|
||
|
|
K4j --> Param["BaseParam/BaseDTO"]
|
||
|
|
K4j --> Ex["GlobalExceptionHandlerAdvice"]
|
||
|
|
```
|
||
|
|
|
||
|
|
图表来源
|
||
|
|
- [Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)
|
||
|
|
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
|
||
|
|
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
|
||
|
|
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
|
||
|
|
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
|
||
|
|
- [BaseParam.java](file://crm-base/src/main/java/com/crm/base/domain/param/BaseParam.java)
|
||
|
|
- [BaseDTO.java](file://crm-base/src/main/java/com/crm/base/domain/dto/BaseDTO.java)
|
||
|
|
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)
|
||
|
|
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
|
||
|
|
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
|
||
|
|
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
|
||
|
|
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
|
||
|
|
- [BaseParam.java](file://crm-base/src/main/java/com/crm/base/domain/param/BaseParam.java)
|
||
|
|
- [BaseDTO.java](file://crm-base/src/main/java/com/crm/base/domain/dto/BaseDTO.java)
|
||
|
|
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
|
||
|
|
|
||
|
|
## 性能考虑
|
||
|
|
- 扫描范围：仅扫描必要的Controller包，减少元数据生成开销。
|
||
|
|
- 分组与标签：合理分组与标签，避免过多无意义端点影响渲染性能。
|
||
|
|
- 生产禁用：在生产环境关闭文档与OpenAPI端点，避免不必要的资源消耗。
|
||
|
|
- 缓存策略：对静态资源与OpenAPI JSON进行缓存，提升加载速度。
|
||
|
|
|
||
|
|
## 故障排查指南
|
||
|
|
- 文档无法访问：检查安全配置是否放行了/doc.html与OpenAPI端点。
|
||
|
|
- 在线调试失败：确认Authorization头是否正确注入，JWT过滤器是否解析成功。
|
||
|
|
- 参数校验不生效：检查参数注解是否正确使用，全局异常处理器是否返回统一响应。
|
||
|
|
- 错误码不一致：核对ResultCodeEnum与实际业务逻辑是否匹配。
|
||
|
|
|
||
|
|
章节来源
|
||
|
|
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
|
||
|
|
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
|
||
|
|
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
|
||
|
|
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
|
||
|
|
|
||
|
|
## 结论
|
||
|
|
通过Knife4j的统一配置与增强能力，结合安全框架与统一结果封装，可实现高质量的API文档体系。在多环境下灵活启用或禁用文档功能，既能满足开发与测试需求，又能保障生产安全。建议持续优化分组与注解描述，提升文档的可读性与可用性。
|
||
|
|
|
||
|
|
## 附录
|
||
|
|
- 最佳实践清单：
|
||
|
|
- 为每个Controller添加分组与标签。
|
||
|
|
- 使用注解完善字段描述、示例值与校验规则。
|
||
|
|
- 在生产环境禁用文档与OpenAPI端点。
|
||
|
|
- 统一错误码与响应体，确保文档示例稳定。
|
||
|
|
- 定期审查与更新文档，保持与实际接口一致。
|