跳到主要内容

组织公共工作空间（Organizing）

在 Postman 公共 API 网络 上提供你的 API 之前，Postman 建议遵循这些最佳实践和提示，以帮助 API 使用者开始使用你的 API。

自定义你的团队资料​

使用有关 你团队的重要信息自定义你的团队资料。 添加将你标识为公共 API 网络上真实公司的信息。默认情况下，你的个人资料仅对你的 Postman 团队可见。 公开你的团队资料 ，使你的资料显示在 Postman 的 探索 页面上。

编辑你的团队资料

组织公共工作空间​

你可以使用集合和文件夹在公共工作空间中组织请求，以帮助消费者开始与你的 API 进行交互。集合使你能够对保存的请求进行分组，而文件夹使你能够按类别（例如域、服务和用例）将请求组织到文件夹中。

工作空间是一组模式、集合、变量、测试等，它们描述了如何与你的 API 交互。通常，开发人员在学习如何与 API 交互时从集合开始。将你的请求组织在集合和文件夹中将有助于引导消费者提出与其兴趣相关的请求。

为不同用例创建 API 示例​

你可以 创建 包含特定示例用例的集合，以帮助消费者 Forking 你的集合并开始与你的 API 进行交互。示例用例可以包括集成、自动化、身份验证和授权等。

编辑集合详细信息

为不同的用例创建环境​

你可以为不同的用例（例如测试和生产） 创建环境，并将它们添加到你的公共工作空间。 这有助于消费者了解他们需要为他们的用例使用你的 API 配置什么。

保护敏感数据​

创建和共享环境变量 时，将示例值指定为变量的初始值。不要将敏感数据添加为初始值，因为它与可以访问环境的用户共享。Current 值用于你的本地 Postman 实例，并且永远不会同步到你的帐户或与你的团队共享，除非你选择保留它。

添加环境

编写详细文档​

为每个集合和请求编写详细的 文档 ，以帮助消费者了解如何使用你的 API。以下最佳实践将帮助你编写清晰简洁的文档：

  • 标准化工作空间中的语言及其 API。
  • 为请求、集合和文件夹使用有意义的名称。使用开发人员期望的名称。
  • 在整个集合中重复使用变量。使用有意义的变量名称，并为其相关值设定明确的期望值。

要了解有关编写详细文档的更多信息，请参阅 The Good Documentation Checklist 。

定义和描述变量​

对于你的 变量 ，你可以编写描述预期值的文档并提供示例值。变量可以独立定义或存储在环境中，然后跨集合应用，使你能够将变量用于身份验证、分页和使用 API 的其他方面。变量还可以定义跨多个 API 和集合的状态。

为文件夹和请求编写描述​

在集合或文件夹级别，Postman 建议编写详细 说明 ，解释如何注册和开始使用你的 API。你可以在描述中使用关键字来增加 API 在自然搜索结果和 Postman 搜索结果中的发现率。

Postman 编辑器

要了解有关集合和文件夹的更多信息，请参阅 使用集合 。

向请求添加示例​

保存 API 请求、响应和消息的 示例，以便 在你的文档中使用示例 。这使消费者能够使用示例数据测试你的 API。

文档中的示例

创建说明如何使用你的 API 进行授权的文档。如果你有多个 API 请求工作流或更复杂的授权模式，你可以在 工作空间描述 或 文档描述 中提及这一点。要了解更多信息，请参阅 包括授权详细信息 。

文档中的授权类型