编辑 API 定义
你可以使用 API 定义来创建 API 的结构。API 定义可以由一个或多个文件组成。如果你的 API 没有定义，你可以导入定义或从样板示例定义开始。
Postman support OpenAPI（版本 1.0、2.0、3.0 和 3.1）、RAML（0.8 和 1.0）、protobuf（协议缓冲区）（2.0 和 3.0）、GraphQL 或 WSDL（1.0 和 2.0）定义。OpenAPI 定义可以是 JSON 或 YAML。RAML 定义必须是 YAML。Protobuf 定义是
.proto文件。GraphQL 定义可以是 JSON 或 GraphQL SDL。WSDL 定义必须是 XML。
生成 API 定义
如果你的 API 没有定义，你可以生成一个你可以编辑的示例定义。
在边栏中选择API ，然后选择一个 API。
在 API 的概览中，在 Definition旁边，选择+并选择Author from scratch。
你还可以在边栏中选择 API，然后选择创建。
选择定义类型和格式。
如果你想从样本定义开始，请选中使用样板复选框。
选择创建定义。
导入 API 定义
你可以将文件导入你的 API 以定义你的 API。
在边栏中选择API ，然后选择一个 API。
在 API 的概述中，在 Definition旁边，选择+并选择Import files。
你还可以在边栏中选择 API，然后选择“导入”。
选择“选择文件”并选择要导入的文件。
选择导入。
你还可以从文件夹、链接、代码存储库或 API 网关导入 API。了解有关 导入 API 的 更多信息。
编辑 API 定义文件
要编辑 API 定义，请在边栏中选择一个 API 将其展开，然后选择Definition。在边栏中选择一个 API 定义文件以打开它进行编辑。
你还可以从 API 的概述中编辑你的定义。在定义下，选择查看文件。
编辑器的左窗格显示 API 定义的概要。当你第一次打开编辑器时，顶层节点是展开的，你可以选择一个节点来展开或折叠它。在大纲中选择一个元素以在编辑器中跳转到它。你还可以选择 API 定义大纲图标 
来隐藏或显示大纲。
在 API 定义编辑器中，当你将鼠标悬停在#ref组件上并按⌘或Ctrl时，弹出窗口会显示参考组件的前 200 个字符。按住 ⌘或Ctrl键的同时选择组件可跳转到参考位置。
API 定义编辑器的右上角有内容美化、换行、复制、更改文件格式和搜索等选项。完成编辑 API 定义后，选择保存。
Postman 会在你处理 API 定义时指出任何 验证错误。
使用多文件 API 定义
你的 API 定义可以跨越多个文件和文件夹。这称为多文件 API 定义。OpenAPI 2.0 和 3.0 API 以及 protobuf 2.0 和 3.0 API 支持多文件 API 定义。
多文件 API 定义由以下组件组成：
- API 定义- API 的完整定义，包含其中的所有文件。
- 文件- 指定 API 定义的一个或多个文件。
- 根文件- 承载 API 定义的操作的顶级文件。有关根文件的更多信息，请参见下文。
- 文件夹- 你可以在 API 定义中创建文件夹来组织文件。（你也可以在文件夹中添加文件夹。）
多文件 API 定义不支持架构同步集成。相反，使用 API 版本控制 与存储库同步。
你无法使用 Postman API 管理多文件 API 定义。
关于根文件
API 定义的根文件包含对 API 定义中其他文件的引用。如果你制作了 API 定义中所有文件之间关系的树状图，则根文件将是树顶部的文件。当你 创建新的 API 定义 或 导入 API 时，Postman 会根据跨文件的引用来确定根文件。API 定义不支持作为外部链接或存在于单独 API 中的引用。
对于 OpenAPI 2.0 和 3.0 API 定义，Postman 在导入或创建 API 定义时根据文件中的内容和引用检测根文件。你不能将文件设置为 OpenAPI 定义的根目录。OpenAPI 定义可以有一个根文件。如果删除根文件，Postman 会自动重新计算下一个候选根文件。
对于 protobuf API 定义，在导入 API 时，Postman 会检测其中存在服务定义的所有文件，并将其中一个标记为根文件。如果有多个候选根文件，你可以将另一个文件设置为根文件。选择边栏中文件
旁边的更多操作图标 ，然后选择标记为根。.proto
编辑多文件 API 定义
要编辑多文件 API 定义，请在边栏中选择一个 API 将其展开，然后选择Definition。如果你的定义包含文件夹，请在边栏中选择一个文件夹以将其展开并查看其内容。选择一个文件以打开它进行编辑。
添加文件和文件夹
你可以将文件和文件夹添加到多文件 API 定义中。在边栏中，选择定义 旁边的更多操作图标 ，然后选择添加文件或添加文件夹。
要将文件添加到文件夹，请选择 文件夹旁边的更多操作图标，然后选择添加文件。你可以通过在边栏中拖动来重新排列文件和文件夹。你还可以通过选择更多操作图标 来重命名或删除文件或文件夹 。
当你将文件添加到单文件 OpenAPI 2.0 或 3.0 定义，或者添加到 protobuf 2.0 或 3.0 定义时，它会转换为多文件 API 定义。现有的定义文件成为根文件。
删除文件和文件夹
要删除定义文件或文件夹，请选择该项目旁边的更多操作图标 ，然后选择删除。删除文件或文件夹不会影响添加到 API 的其他元素，例如集合。
你可以使用 Changelog 恢复已删除的定义文件。
选择右侧栏中的变更日志图标 ，然后选择要恢复的定义文件下方的恢复。
关于定义 ID。当你向 API 添加定义时，Postman 会为 API 分配一个定义 ID。你可以通过打开 API 并选择
右侧栏中的信息图标来查看定义 ID。定义 ID 充当 API 中所有定义文件的容器。如果删除所有定义文件，则不会删除定义 ID 本身。如果你随后添加新的定义文件，定义 ID 将与以前相同。
查看 API 定义中的规则违规
当你在编辑器中创建 API 定义时，Postman 会根据为你的团队配置的 Postman API Governance 和 API 安全 规则自动检查它。Postman 会在编辑器下方显示任何违反规则的行为。解决这些问题可以改进你的 API 定义。
要了解有关支持的 API 描述格式、Postman 中预配置的规则以及如何创建新规则的更多信息，请参阅 API 定义中的规则违规 。
要查看任何违反规则的情况，请选择Violations found in definition旁边的Rule。每个规则违规都在其自己的行中，包括违规名称和规则类型（Governance或安全）。规则名称旁边的数字告诉你 Postman 在你的 API 定义中发现规则违规的次数。
选择要检查每个规则违规的数字。每个违反规则的实例都有问题的简短描述以及文件中发生规则违反的行。当你选择违反规则时，Postman 会突出显示触发它的定义部分。
要了解有关规则违规的更多信息并获取有关如何修复它的信息，请选择规则描述旁边的可能的修复。这将打开相关的学习中心页面。
当你更新 API 定义时，Postman 会重新检查它。如果你的更改解决了问题，Postman 将从列表中删除规则违规。
隐藏违规行为
要隐藏 API 定义的规则违规，请执行以下操作：
选择违反规则旁边的隐藏。
选择你要隐藏它的原因，然后再次选择隐藏。
这将隐藏当前 API 的规则违规。如果多次违反特定规则，你可以单独隐藏每个实例。
要全局隐藏规则违规，你可以使用可 配置的 API Governance 规则 或 可配置的 API 安全规则 。
当你或你的团队的其他成员隐藏违反规则时，Postman 会在编辑器的规则选项卡中显示一条消息，指示隐藏了多少。
要稍后重新启用规则，请执行以下操作：
- 选择审查。
- 查看你的隐藏规则并选择
你要重新启用的规则旁边的眼睛图标。
