以 OpenAPI 文件维护接口

以 OpenAPI 文件维护接口（简称 spec 模式）允许你直接在 Apifox 中维护 OpenAPI 规范文件。Apifox 会解析这些文件，并基于规范生成可导航的接口结构、接口文档、调试视图及相关资源。

创建项目或导入 OpenAPI 时，可以选择 以 OpenAPI 文件维护接口（Spec 模式）。

当你的团队符合以下场景时，推荐使用该模式：

已经使用 OpenAPI 或 Swagger 的 YAML / JSON 文件维护接口定义；

希望通过基于文件的流程评审 API 变更；

将 API 定义保存在 Git 仓库中；

希望 API 设计流程自然融入规范优先或代码仓库协作流程。

spec 模式如何工作

在以可视化界面维护的项目中，接口通常通过可视化表单创建和编辑。

在 spec 模式项目中，主要工作区基于文件。你可以维护如下文件：

openapi.yaml

openapi.json

Swagger 2.0 文件

Markdown 文件及其他辅助项目文件

Apifox 会解析规范文件，并将其转换为可导航的接口结构。你可以编辑原始文件，使用支持的表单视图，校验规范文件，预览生成后的接口文档，并根据项目来源保存或推送变更。

创建 spec 模式项目

只有 通用项目 可以选择该模式。gRPC 和 Dubbo 项目暂不支持该模式。

在 主窗口 中选择团队，进入 「团队项目」，点击 「新建项目」。

确认项目类型为 通用项目，然后选择 「以 OpenAPI 文件维护接口」。

选择 「连接 Git 仓库」 或 「不使用 Git 创建」。

如果选择连接 Git 仓库，请按照页面提示完成配置。

填写项目名称，并按需设置图标、项目语言和项目权限。

点击创建。项目会打开 Specs 工作区。

空白项目不会自动生成 openapi.yaml，进入 Specs 工作区后，需手动点击创建或导入。

除新建空白项目外，在导入 OpenAPI / Swagger 文件时也可以选择该模式。详见新建 API 项目和导入 OpenAPI/Swagger。

spec 模式项目不会包含示例项目数据。项目中的接口内容来自你的规范文件。

当前环境如果还没有配置 Git 应用，「连接 Git 仓库」会不可用，只能选择「不使用 Git 创建」。

支持的规范文件

Apifox 支持以下格式的 OpenAPI / Swagger 文件：

JSON

YAML

支持的文件扩展名：

.json

.yaml

.yml

支持的规范版本：

OpenAPI 3.1

OpenAPI 3.0

Swagger 2.0

文件根节点必须包含 openapi 或 swagger 字段。

示例：

Specs 工作区

spec 模式项目的左侧边栏中会出现 Specs 工作区。这里是管理规范文件和同步变更的主要入口。Specs 工作区包含：

文件浏览器：浏览和管理规范文件及文件夹。

接口结构树：浏览解析后的 OpenAPI 内容，例如概览、接口、数据模型和定义。

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

当你在接口结构树中选择接口、数据模型或其他支持的节点时，Apifox 会打开源文件中对应的位置，方便你在文件视角和接口视角之间切换。

编辑规范文件

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

代码视图

使用代码视图可以直接编辑 YAML、JSON、Markdown 及其他文本文件。这是 spec 模式中默认的编辑方式。

表单视图

对于支持的 OpenAPI 节点，Apifox 也提供表单视图。你可以通过结构化控件编辑常见接口字段，同时保持底层规范文件作为事实来源。

表单视图可能支持以下节点：

API 概览

接口

数据模型

定义

如果当前选择的文件或节点不支持表单视图，Apifox 会保持在代码视图中。

编辑、校验与预览

spec 模式提供规范校验和文档预览能力。

校验

校验面板会展示当前规范中检测到的问题，包括警告和错误。

你可以在保存或推送变更前，通过该面板发现语法问题、缺失的必填字段和规范规则问题。

预览

预览面板会展示当前选中的规范节点在生成后的接口文档中的展示效果。

对于接口节点，预览内容可能包括：

文档：生成后的接口文档。

调试 / Try it out：基于当前接口定义发送请求的调试面板。

对于数据模型、定义和概览节点，预览区域会展示生成后的文档视图。

校验和预览使用同一个侧边面板。打开其中一个面板时，另一个面板会关闭。

保存、提交和同步变更

变更的保存方式取决于项目来源。

Git 托管的 spec 模式项目

对于连接外部 Git 仓库的项目：

在 Specs 工作区中编辑文件。

查看已修改、新增、重命名或删除的文件。

点击 「提交并推送」。

选择需要包含在本次提交中的文件。

输入提交信息。

将变更推送到已连接的 Git 仓库。

当其他成员向仓库推送变更后，你可以将最新文件同步到 Apifox。如果已启用 Webhook

同步，Git 仓库中的推送事件可以自动触发同步。

Apifox 存储托管的 spec 模式项目

不使用 Git 创建的项目会使用 Apifox 内部存储，而不是外部 Git 仓库。

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

界面中的操作文案可能有所不同：

使用 「同步」 保存并同步变更。

使用 「保存」 保存变更。

Git 服务信息和外部 Webhook 设置会被隐藏。

将 OpenAPI / Swagger 导入 spec 模式项目

新建项目并同时带入文件时，请用首页 「导入项目」。解析 OpenAPI / Swagger 成功后，选择 「以 OpenAPI 文件维护接口」，确认项目名称，然后点击 「创建并导入」。此路径不会出现可视化导入中的预览和导入选项。

若项目已存在，可在 项目设置 → 导入数据 中导入 OpenAPI / Swagger。

对于 Apifox 存储托管的 spec 模式项目，Apifox 会将导入的文档保存为规范文件，并解析该文件以更新生成后的接口结构。导入的文档可能会保存为：

reference/openapi.json

reference/openapi.yaml

随后 Apifox 会启动同步任务，解析文件并更新项目接口。

对于 Git 托管的 Spec 模式项目，若在项目内使用「导入数据」功能，系统不会将导入的文档写入 reference/openapi.* 文件

与「以可视化界面维护接口」模式的区别

能力	以可视化界面维护接口	以 OpenAPI 文件维护接口
主要接口维护方式	可视化接口编辑器	OpenAPI / Swagger 文件
接口创建入口	接口树和可视化表单	Specs 工作区
接口定义来源	Apifox 项目数据	规范文件
Git 基于文件的协作	非必需	创建时可连接仓库，也可以先不使用 Git
适用场景	可视化API 设计与协作	规范优先的 API 工作流

Webhook 同步和权限

Webhook 同步是可选能力，推荐希望 Apifox 自动跟随仓库推送更新的团队使用。

启用 Webhook 同步后：

Apifox 会在已连接的 Git 服务中注册 Webhook。

支持的推送事件可以触发同步。

安装 Webhook 通常需要对应仓库的管理员权限。

权限要求：

导入 OpenAPI / Swagger 数据需要项目导入权限。

向 Git 仓库推送变更需要仓库写入权限。

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

如果跳过 Webhook 安装，仍然可以手动同步。

注意事项和限制

「以 OpenAPI 文件维护接口」当前为 Beta 功能。

只有通用项目可以选择该模式。

Specs 工作区仅在 spec 模式项目中显示。

spec 模式项目不会创建示例接口数据。

空白创建不会自动生成规范文件。需要在 Specs 中新建，或通过导入带入。

规范文件是接口定义的事实来源。建议通过 Specs 工作区修改规范文件，或通过 Git 同步变更。

可视化维护中的部分接口创建操作在 spec 模式项目中会被隐藏。

Swagger UI 的 HTML 页面不是有效的 OpenAPI 导入文件。请使用 .json、.yaml 或 .yml 规范文件的直接 URL。

spec 模式如何工作#

创建 spec 模式项目#

支持的规范文件#

Specs 工作区#

编辑规范文件#

代码视图#

表单视图#

编辑、校验与预览#

校验#

预览#

保存、提交和同步变更#

Git 托管的 spec 模式项目#

Apifox 存储托管的 spec 模式项目#

将 OpenAPI / Swagger 导入 spec 模式项目#

与「以可视化界面维护接口」模式的区别#

Webhook 同步和权限#

注意事项和限制#