Apidog Docs
🇨🇳 简体中文
  • 🇺🇸 English
  • 🇯🇵 日本語
  • 🇪🇸 Español
  • 🇰🇷 한국인
  • 🇨🇳 简体中文
  • 🇵🇹 Português
🇨🇳 简体中文
  • 🇺🇸 English
  • 🇯🇵 日本語
  • 🇪🇸 Español
  • 🇰🇷 한국인
  • 🇨🇳 简体中文
  • 🇵🇹 Português
🇨🇳 简体中文
  • 🇺🇸 English
  • 🇯🇵 日本語
  • 🇪🇸 Español
  • 🇰🇷 한국인
  • 🇨🇳 简体中文
  • 🇵🇹 Português
HomeLearning Center
Support CenterAPI ReferencesDownloadChangelog
HomeLearning Center
Support CenterAPI ReferencesDownloadChangelog
  1. Apidog Swagger 扩展
  • Apidog 学习中心
  • 入门
    • Apidog 简介
    • Apidog 中的基本概念
    • 导航 Apidog
    • 快速开始
      • 概述
      • 创建端点
      • 发送请求
      • 添加断言
      • 创建测试场景
      • 共享 API 文档
      • 探索更多
    • 迁移到 Apidog
      • 概述
      • 手动导入
      • 定时导入(绑定数据源)
      • 导入选项
      • 导出数据
      • 导入自
        • 从 Postman 导入
        • 导入 OpenAPI 规范
        • 导入 cURL
        • 导入 Markdown
        • 从 Insomnia 导入
        • 从 apiDoc 导入
        • 导入 .har 文件
        • 导入 WSDL
  • Mock API 数据
    • 概述
    • Smart Mock
    • 自定义模拟
    • 模拟优先级顺序
    • 模拟脚本
    • 云端模拟
    • 自托管 Runner 模拟
    • 模拟语言(区域设置)
  • 账号与偏好设置
    • 账户设置
    • 生成 OpenAPI 访问令牌
    • 通知
    • 语言设置
    • 快捷键
    • 网络代理配置
    • 备份数据
    • 更新 Apidog
    • 删除账户
    • 实验性功能
  • 发送请求
    • 概述
    • SSE 调试
    • MCP 客户端
    • Socket.IO
    • WebSocket
    • Webhook
    • SOAP 或 WebService
    • GraphQL
    • gRPC
    • 使用请求代理 Agent 进行调试
    • 创建请求
      • 请求历史
      • 请求基础
      • 参数和主体
      • 请求头部
      • 请求设置
      • 调试请求
      • 将请求保存为端点
      • HTTP/2
    • 身份验证与授权
      • 概述
      • CA 和客户端证书
      • 授权类型
      • Digest Auth
      • OAuth 1.0
      • OAuth 2.0
      • Hawk 身份验证
      • Kerberos
      • NTLM
      • Akamai EdgeGrid
    • 响应和 Cookie
      • 查看 API 响应
      • 管理 Cookie
      • 概述
  • 开发和调试 API
    • 概述
    • 生成请求
    • 发送请求
    • 调试用例
    • 测试用例
    • 动态值
    • 验证响应
    • Design-First vs Request-First
    • 生成代码
    • 环境与变量
      • 概览
      • 使用变量
      • 环境管理
    • Vault 密钥
      • 概述
      • HashiCorp Vault
      • Azure Key Vault
      • AWS Secrets Manager
    • 动态值模块
      • Airline
      • 动物
      • 颜色
      • 商务
      • Company
      • 数据库
      • 数据类型
      • 日期
      • Finance
      • 食物
      • Git
      • Hacker
      • Helpers
      • 图像
      • Internet
      • 位置
      • Lorem
      • 音乐
      • 数字
      • Person
      • 电话
      • 科学
      • String
      • System
      • Vehicle
      • Word
    • 前置和后置处理器
      • 概述
      • 断言
      • 提取变量
      • 等待
      • 安全
      • 数据库操作
        • 概述
        • MySQL
        • MongoDB
        • Redis
        • Oracle 客户端
      • 使用脚本
        • 概述
        • 预处理器脚本
        • 后处理器脚本
        • 公共脚本
        • Postman 脚本参考
        • 调用其他编程语言
        • 使用 JS 库
        • 可视化响应
        • 脚本示例
          • 断言脚本
          • 使用变量
          • 修改请求
          • 其他示例
    • API 调试
      • AI Agent Debugger
      • A2A 调试器
  • 设计 API
    • 概述
    • 创建新的 API 项目
    • 端点基础
    • API 设计指南
    • 模块
    • 配置多个请求主体示例
    • 组件
    • 通用字段
    • 全局参数
    • 端点变更历史
    • 评论
    • 批量端点管理
    • 自定义协议 API
    • Spec-first 模式(Beta)
    • 安全方案
      • 概述
      • 创建安全方案
      • 使用安全方案
      • 在线文档中的安全方案
    • 高级功能
      • 自定义端点字段
      • 关联的测试场景
      • 端点状态
      • 参数列表的外观
      • 端点唯一标识
    • Schemas
      • 概述
      • 创建新 Schema
      • 构建 Schema
      • 从 JSON 等生成 Schema
      • oneOf, allOf, anyOf
      • 使用 Discriminator
  • Apidog Europe
    • Apidog Europe
  • API 测试
    • 概述
    • 测试场景
      • 创建测试场景
      • 在请求之间传递数据
      • 流程控制条件
      • 从端点和端点用例同步数据
      • 从其他项目导入端点和端点用例
      • 导出测试场景
    • 测试报告
      • 测试报告
    • 运行测试场景
      • 运行测试场景
      • 批量运行测试场景
      • 数据驱动测试
      • 共享测试数据
      • 定时任务
      • 管理来自其他项目的 API 运行环境
    • 测试套件
      • 概述
      • 创建测试套件
      • 编排测试套件
      • 本地运行测试套件
      • 通过 CLI 运行测试套件
      • 定时任务
    • 测试 API
      • 集成测试
      • 性能测试
      • 端到端测试
      • 回归测试
      • 契约测试
    • Apidog CLI
      • 概述
      • 安装和运行 Apidog CLI
      • Apidog CLI 选项
    • CI/CD
      • 概述
      • 与 Github Actions 集成
      • 与 Gitlab 集成
      • 与 Jenkins 集成
      • 通过 Git Commit 触发测试
  • 发布 API 文档
    • 概述
    • 支持的 API 技术
    • 快速分享
    • 查看 API 文档
    • Markdown 文档
    • 发布文档站点
    • 自定义登录页面
    • 自定义布局
    • 自定义 CSS、JavaScript、HTML
    • 自定义域名
    • AI 功能
    • SEO 设置
    • 高级设置
      • 文档搜索
      • CORS 代理
      • 集成 Google Analytics
      • 文件夹树设置
      • 可见性设置
      • 在文档 URL 中嵌入值
    • API 版本
      • 概述
      • 创建 API 版本
      • 发布 API 版本
      • 共享带有 API 版本的端点
  • 分支
    • 概述
    • 创建 Sprint 分支
    • 在分支中测试 API
    • 在分支中设计 API
    • 合并 Sprint 分支
    • 管理 Sprint 分支
    • AI Branch(Beta)
  • AI 功能
    • 概述
    • 启用 AI 功能
    • 生成测试用例
    • 使用 AI 修改 Schema
    • 端点合规性检查
    • API 文档完整性检查
    • AI 驱动的字段命名
    • 常见问题
  • Apidog MCP 服务器
    • 概述
    • 将 Apidog 项目连接到 AI
    • 将已发布的文档连接到 AI
    • 将 OpenAPI 文件连接到 AI
  • 最佳实践
    • 处理 API 签名
    • 访问受 OAuth 2.0 保护的 API
    • 协作工作流
    • 管理身份验证状态
  • 离线空间
    • 概述
  • 管理
    • 管理项目
      • 管理项目
      • 通知设置
      • 管理项目成员
      • 项目资源
        • 数据库连接
        • Git 连接
    • 管理团队
      • 管理团队
      • 管理团队成员
      • 团队活动
      • 团队角色与权限
      • 团队资源
        • General Runner
        • 团队变量
        • 请求代理 Agent
      • 实时协作
        • 团队协作
    • 入门检查清单
      • 基本概念
      • 入门指南
    • 管理组织
      • 管理组织
      • 组织角色与权限
      • 套餐管理
        • 组织中的账单管理员
      • 单点登录 (SSO)
        • SSO 概述
        • 配置 Microsoft Entra ID
        • 配置 Okta
        • 为组织配置 SSO
        • 管理用户账户
        • 将组映射到团队
      • SCIM 配置
        • SCIM 预配简介
        • Microsoft Entra ID
        • Okta
      • 组织资源
        • 自托管 Runner
  • 计费
    • 概述
    • 积分
    • 升级您的套餐
    • 替代支付方式
    • 管理订阅
    • 将付费团队移入组织
  • 附加组件
    • API Hub
    • Apidog Intellij IDEA 插件
    • 浏览器扩展
      • Chrome
      • Microsoft Edge
    • 请求代理
      • Web 中的请求代理
      • 共享文档中的请求代理
      • 客户端中的请求代理
  • 数据与安全
    • 数据存储和安全
    • 用户数据隐私与安全
    • 请求路由与数据安全
  • 参考
    • API 设计优先方法
    • Apidog OpenAPI 规范扩展
    • JSONPath
    • XPath
    • 正则表达式
    • JSON Schema
    • CSV 文件格式
    • 安装 Java 环境
    • Runner 部署环境
    • Apidog Markdown 语法
    • Apidog Swagger 扩展
      • 概述
      • x-apidog-folder
      • x-apidog-status
      • x-apidog-name
      • x-apidog-maintainer
    • Apidog JSON Schema 扩展
      • 概述
      • x-apidog-mock
      • x-apidog-orders
      • x-apidog-enum
  • 支持中心
    • Apidog Support Center
    • 导入/导出
      • 如何将 API 数据导入 Apidog?
      • 如何在 Apidog 中导入 cURL?
      • 如何将 Postman 环境迁移到 Apidog?
      • 如何在导入 Swagger/OpenAPI 时自动对端点分组?
    • 发送请求
      • Apidog 支持 Socket.IO 吗?
      • 为什么参数值中的 “+” 会被解码为空格?
      • 如何在 Apidog 中发送请求?
      • 如何在 Apidog 中发送 graphQL 请求?
      • 如何在 Apidog 中发送 gRPC 请求?
      • 如何在 Apidog 中发送 SOAP/WebService 请求?
      • 如何在 Apidog 中发送 WebSocket 请求?
      • Apidog 是否支持 WebSocket API 中的预请求/测试脚本和断言?
      • 如何在 Apidog 中发送 SSE 请求?
      • 如何在文件夹级别添加默认头部?
      • Apidog 是否支持 gRPC API 中的预请求/测试脚本和断言?
      • ELANREFUSED.DNS 解析器错误
      • 为什么我在发送请求时会收到 “socket hang up” 错误?
      • 修复请求错误
        • 修复 read ECONNRESET 错误
        • 修复 ECONNREFUSED 错误
        • 修复 ETIMEDOUT 错误
        • 修复 ENOTFOUND: Couldn't resolve host 错误
        • 修复 ENOTFOUND: getaddrinfo ENOTFOUND www 错误
        • 修复 connect EHOSTUNREACH 错误
    • 设计 API
      • 如何在路径中使用变量?
      • 我可以将响应组件用作默认响应吗?
      • 如何查看谁修改了端点?
      • 如何在 Apidog 中批量删除端点文件夹?
      • 如何批量为端点路径添加/移除前缀?
      • 如何在 Schema 编辑器中移动属性的层级?
      • 如果一个字符串属性有多个枚举值,并且会在多个位置使用,如何在整个文档中一致地引用这个枚举?
      • 如何获取 Apidog 资源文件夹 ID?
      • 如何获取 Apidog 的资源文件夹 ID?
      • 如何在 URL 路径中使用变量?
      • 如果端点、文档或测试场景被意外删除,我该怎么办?
      • Apidog 是否支持自定义端点的请求代码?
      • 将 Swagger/OpenAPI 导入 Apidog 时,如何自动对端点分组?
      • 如何在模拟响应中生成不重复的数组数据?
      • 为什么路径中不支持输入 "#"?
    • 调试 API
      • Apidog 如何与第三方密钥管理系统集成?
      • 为什么同一个请求在其他工具(如 Postman)中可以正常工作,但在 Apidog 中不行?
      • 如何在 Apidog 中从数据库获取变量值?
      • 如何将环境从其他工具迁移到 Apidog?
      • 如何在 Apidog 中使用脚本进行断言?
      • JSONPath 只能提取数组。如何在 Apidog 中从数组中提取单个元素?
      • 当不同环境具有不同的数据库账号凭据时,如何在 Apidog 中配置数据库操作?
      • 如何在自定义脚本中获取服务基础 URL?
      • 当 API 响应过大时,为什么 Apidog 会报告超出最大 Node.js 字符串长度的错误?
      • 控制台打印的大小限制是多少?为什么打印大文件时会出现错误?
      • 如何解决 Windows 上的 DB2 数据库连接错误?
      • 为什么我在 Apidog 中连接 Oracle 数据库时会遇到错误 NJS-045?
      • 如何在 Apidog 自定义脚本中生成动态值?
      • 为什么客户端请求同一个端点可以成功,但在 Web 端调试时却出现错误:“Unable to request address”?
      • 为什么响应过大时 Apidog 会报错?
      • 如何使用 Apidog 录制端点?
      • 定义端点响应时,是否允许端点没有响应内容?
      • 如何在自定义脚本中获取服务的 baseURL?
      • 如何在 Apidog 中查看原始报文?
      • 为什么在发起请求时会看到 “Invalid URI xxx” 错误?
      • 如何在 Apidog 脚本中发起异步请求?
      • 为什么发送请求时会看到 “Couldn't resolve host” 消息?
      • 控制台打印大小限制是多少?为什么打印大文件时会报错?
      • 如何在端点请求中上传文件?
      • 如果 Apidog 崩溃或响应数据不显示,该怎么办?
      • Apidog 用于 OAuth2.0 的官方重定向 URI
    • Mock API 数据
      • 如何自动模拟 API?
      • Apidog 模拟可以做什么?
      • 如何在 Apidog 中模拟固定 API 数据?
      • 如何在 Apidog 中模拟条件数据?
      • 如何在 Apidog 中启用云端模拟?
      • 如何在 Apidog 中启用自托管模拟?
      • Apidog 支持模拟 WebSocket API 吗?
      • 为什么浏览器请求模拟端点时不返回内容?
    • 自动化测试
      • 为什么测试场景在我的本地客户端运行没有问题,但在 Apidog CLI 或运行器中运行时会出错?
      • 如何在 Apidog 中创建测试场景?
      • 如何在测试步骤之间传递数据?
      • 为什么我无法成功引用前置步骤数据?
      • 如何在 Apidog 中使用 foreach 循环?
      • 从端点/端点用例同步数据有哪些区别?
      • 如何在 Apidog 中使用测试数据?
      • 如何在 Apidog 的脚本中检索测试数据?
      • 如何在 Apidog 中批量运行测试场景?
      • 如何在 Apidog 中安排测试任务?
      • 如何在 Apidog 中运行性能测试?
      • 如何在性能测试中查看实际请求和响应?
      • 如何在 Apidog 中导出性能测试报告?
      • 如何使用数据库查询结果作为循环 API 请求的参数?
      • 在 CI/CD 期间使用 ApiDog 捕获并验证 Stripe Webhook
      • 如何解决“Error: unable to verify the first certificate on runner”错误?
      • General Runner Docker 容器 “Not Found” 错误。
      • 如何在 Apidog Web 版中为通用 Runner 设置服务器 Host?
      • 为什么定时测试场景最终显示 0 个请求?
      • 如果在 Runner 或 CLI 中找不到文件上传参数,我该怎么办?
      • 如何使用 Runner 运行包含上传文件步骤的测试场景?
      • 如何解决“Error: unable to verify the first certificate on runner”错误?
      • 当 Runner 出现问题时,如何访问和搜索 Runner 日志以识别问题?
      • 如果端点参数是上传文件,并且在 Runner 或 CLI 中找不到,我该怎么办?
      • 为什么 API 用例变更时测试步骤不会自动同步?
      • 为什么在 Markdown 文档中使用多个美元符号会导致某些内容无法正确显示?
      • 自托管 Runner 在执行任务后会在服务器上生成测试报告吗?
      • 我可以为测试场景中的请求添加统一的前置/后置处理器吗?
      • 如何在单次自动化测试运行期间保持动态值一致?
    • 发布 API 文档
      • 如何在已发布的文档中隐藏所有 Apidog 标志?
      • 当 API 规范更新时,API 文档会变化吗?
      • 如何在 Apidog 中将 API 分享给协作者?
      • 如何自定义 Apidog 文档的域名?
      • 如何在 Apidog 中创建多版本文档?
      • Apidog 中发布文档站点的共享范围
      • Apidog 中 Share Doc 列表的共享范围
      • 为什么已发布的共享文档没有显示主机名?
      • 文档用户如何在共享文档中修改 Base URL?
      • 我可以复制已发布的 Apidog 文档用于自己的项目吗?
      • 如何在 Apidog 在线文档中共享头部(例如 Token)?
      • 为什么我的团队成员找不到已发布的文档?
      • 如何修复自定义域名上的 SSL 证书过期或 Cloudflare 526 错误?
      • 自定义 SMTP 配置成功,但允许列表用户未收到 OTP 邮件
    • Markdown
      • 如何使用卡片链接到 Apidog 内的各个页面或端点?
      • 为什么在 Markdown 文档中使用多个 $ 符号时,部分内容无法正确显示?
      • 如何在 Apidog Markdown 中使用透明背景图片?
      • 如何设置 Markdown 表格的列宽?
      • 如何将内部 API、文档、数据模式或文件夹插入到 Markdown 文档中?
      • 如何在 Apidog 卡片组件中添加指向项目内文档或端点的链接?
    • 分支
      • 如何访问迭代分支?
    • 管理
      • 如何静默安装 Apidog 客户端?
      • 为什么我明明拥有管理员权限,却看到“No Permission”错误?
      • 如何查看 Runner 版本号?
      • Apidog 支持 win7 吗?
      • 为什么安装后 Apidog 显示错误“Cannot locate program entry point DiscardVirtualMemory in dynamic link library KERNEL32.dll”?
      • 订阅变更和退款
      • Web 请求有效,但应用出现 “read ECONNRESET”——为什么?
      • Windows 系统更新后为什么无法打开 Apidog?
      • 为什么 Windows 系统更新后 Apidog 无法打开
    • 计费
      • 我可以在 Apidog 中为我的团队设置单独的账单账户吗?
      • Apidog 上的团队访问与计费问题
      • 受邀团队成员无法访问 Apidog。
      • 将个人付费团队转移到组织
    • 本地部署
      • Apidog 自托管(企业)版本中的用户和访问管理
    • Web 与客户端
      • Linux 桌面版的下载与安装
  1. Apidog Swagger 扩展

x-apidog-folder

用法#

用于指定端点所属的文件夹。
Apidog 优先使用 x-apidog-folder 字段。如果该字段不存在,则将使用 tags 字段中的第一个值。
多级文件夹使用正斜杠 / 分隔。其中 \ 和 / 是特殊字符,需要进行转义:\/ 表示字符 /,\\ 表示字符 \。

示例#

"paths": {
    "/pets": {
        "post": {
            ...
            "operationId": "addPet",   
            "x-apidog-folder": "Pet Store/Pet Information"
        }
    }
}

Swagger 注解示例#

输出#

返回 JSON:
{{"translated_content": "...", "review_items": []}}
Modified at 2026-06-09 08:55:47
Previous
概述
Next
x-apidog-status
Built with