Spec-first 模式（Beta）

Spec-first 模式适用于希望将 API 规范文件作为唯一事实来源的团队。在此模式下，你可以直接在 Apidog 中设计和维护 OpenAPI 或 Swagger 文件，在编辑时预览生成的 API 文档，并使文件与 Git 保持同步。

当你的团队已经使用 YAML 或 JSON 规范文件、通过 Git 审查 API 变更，或希望 API 设计自然融入代码仓库工作流时，请使用 Spec-first 模式。

Spec-first 模式的工作方式

在常规 Apidog 项目中，API 通常通过可视化表单创建和编辑。在 Spec-first 项目中，主要工作区是基于文件的。

你会处理如下文件：

openapi.yaml

openapi.json

Swagger 2.0 文件

Markdown 文件和其他支持性项目文件

Apidog 会解析规范文件，并将其转换为可导航的 API 结构。你可以编辑原始文件，使用受支持的可视化表单，验证规范，预览生成的文档，并将更改推送回 Git。

创建 Spec-first 项目

点击 + New Project。

在项目类型选择器中，选择 Spec-first Mode。

连接 Git 提供商，例如 GitHub、GitLab、Azure DevOps 或 Bitbucket。

选择一个组织或工作区，然后选择现有仓库；如果该选项可用，也可以创建新仓库。

选择 Apidog 应同步的主分支。

选择是否安装 webhook。

安装 webhook 后，Git 仓库中的推送可以触发自动同步。这通常需要仓库的管理员权限。如果你没有管理员权限，可以跳过 webhook 安装并手动同步。

输入项目名称，配置成员权限，然后点击 Create。

创建后，Apidog 会执行首次同步。如果仓库的默认分支不是 main，Apidog 会使用仓库分支名称作为项目主分支。

Spec-first 项目不包含示例项目数据。API 内容来自你的规范文件。

Specs 工作区

Spec-first 项目在左侧边栏中包含一个 Specs 工作区。这是管理规范文件和 Git 同步的主要位置。

该工作区包含三个主要区域：

文件浏览器：浏览和管理来自同步仓库的文件和文件夹。

API 结构树：导航已解析的 OpenAPI 内容，例如概览、端点、模式和定义。

编辑器：在代码视图中编辑文件；对于受支持的 OpenAPI 节点，也可在表单视图中编辑。

当你在结构树中选择端点、模式或其他受支持的节点时，Apidog 会打开源文件的相关部分。这样你无需离开 Specs 工作区，就可以在文件级视图和 API 级视图之间切换。

编辑规范文件

编辑器支持不同的文件类型和编辑模式。

代码视图

使用 Code 视图直接编辑 YAML、JSON、Markdown 和其他文本文件。这是在 Spec-first 模式中工作的默认方式。

表单视图

对于受支持的 OpenAPI 节点，Apidog 还提供 Form 视图。你可以通过结构化控件编辑常见 API 字段，同时保持底层规范文件作为唯一事实来源。

表单视图适用于以下受支持的节点：

API 概览

端点

模式

定义

如果所选文件或节点无法在表单视图中编辑，Apidog 会让你保持在代码视图中。

编辑时验证和预览

Spec-first 模式在编辑器头部包含验证和预览工具。

验证

Validation 面板显示当前规范中检测到的问题，包括警告和错误。验证徽标会显示检测到的问题总数。

使用此面板可在提交更改前查找语法问题、缺少的必填字段和规则违规。

预览

Preview 面板显示所选规范节点在生成的 API 文档中的呈现效果。

预览适用于：

API 概览

端点

模式

定义

对于端点，Preview 包括：

Docs：生成的端点文档。

Try it out：用于根据所选端点定义发送请求的请求面板。

对于模式、定义和概览节点，Preview 会显示生成的文档视图。

Validation 和 Preview 使用同一个侧边面板。打开其中一个会关闭另一个。

从 Git 同步更改

当其他团队成员将更改推送到已连接的仓库时，你可以将最新文件拉取到 Apidog。

打开 Specs 工作区。

点击 Specs 侧边栏中的当前分支名称。

点击 Git Pull。

如果已安装 webhook 同步，Apidog 还可以接收来自 Git 提供商的推送事件并自动触发同步。

提交并推送更改到 Git

在 Apidog 中编辑文件后，将你的更改推送回已连接的仓库。

在 Specs 工作区中编辑一个或多个文件。

点击 Changes 以审查已修改、已添加、已重命名和已删除的文件。

点击 Commit & Push。

在 Push to Git repo 模态框中，选择要包含的文件。

输入提交信息。

点击 Push。

如果你不想保留本地编辑，请在推送前使用 Discard all changes。

管理分支

Spec-first 模式支持基于分支的协作。Apidog 会将同步的 Git 分支映射到项目分支，以便你可以在规范的不同版本之间切换。

切换分支

点击 Specs 侧边栏中的分支名称，并从下拉菜单中选择另一个分支。

跟踪现有 Git 分支

如果某个分支存在于 Git 中但尚未导入 Apidog，请点击 Import New Branch，选择该分支并导入。随后 Apidog 会开始跟踪并同步该分支。

创建分支

打开 Project Settings > Git & Branches，然后点击 New Branch，从现有项目分支创建分支。

重新同步分支

如果分支同步失败或文件看起来已过期，请在 Project Settings > Git & Branches 中使用 Re-sync。这会重置该分支的同步状态并再次导入文件。

查看同步日志

如果同步失败，请打开分支操作并选择 View Logs 以检查同步详情。

停止跟踪或删除分支

删除已跟踪的分支会将其从 Apidog 的同步配置中移除。对于非主分支，也可以移除项目分支记录。

Webhook 同步和权限

Webhook 同步是可选的，但推荐希望 Apidog 与仓库推送保持最新状态的团队使用。

启用 webhook 同步后：

Apidog 会在已连接的 Git 提供商上注册一个 webhook。

只会处理受支持的推送事件。

Apidog 会在同步前验证 webhook 签名或令牌。

权限要求：

安装 webhook 通常需要仓库管理员权限。

推送更改需要写入权限。

如果跳过 webhook 安装，仍可使用手动同步。

如果你在项目创建期间跳过了 webhook 安装，可以稍后从 Project Settings > Git & Branches 安装。

基于存储的 Spec-first 项目

某些 Spec-first 项目可能会使用 Apidog 的内部存储，而不是外部 Git 仓库。

这些项目仍然使用 Specs 工作区、基于文件的编辑、验证、预览和分支管理。

UI 标签略有不同：

Git Pull 显示为 Sync。

Commit & Push 显示为 Save。

Git 提供商信息和外部 webhook 设置会被隐藏。

注意事项和限制

Spec-first 模式目前处于 beta 阶段。

Specs 工作区仅出现在 Spec-first 项目中。

Spec-first 项目不会创建示例 API 数据。

规范文件是唯一事实来源。更改应通过 Specs 工作区进行，或通过 Git 同步。

如果你没有足够的仓库权限，webhook 安装可能会失败。只要你拥有写入权限，仍可使用手动同步。

Spec-first 模式（Beta）

Spec-first 模式的工作方式#

创建 Spec-first 项目#

Specs 工作区#

编辑规范文件#

代码视图#

表单视图#

编辑时验证和预览#

验证#

预览#

从 Git 同步更改#

提交并推送更改到 Git#

管理分支#

切换分支#

跟踪现有 Git 分支#

创建分支#

重新同步分支#

查看同步日志#

停止跟踪或删除分支#

Webhook 同步和权限#

基于存储的 Spec-first 项目#

注意事项和限制#