设计 API 合约绝非易事。从 API 的初始计划（包括其战略和功能目标）开始，生成 API 合约是首要任务。将此计划转换为实际的人类和机器可读的 API 合约需要大量时间和精力，特别是考虑到这将影响 API 未来的开发和使用。良好的开发者体验 (DX) 已开始在用户选择和采用 API 时发挥重要作用，并且 良好的 DX 始于设计上的一致性。但一致的设计不仅仅是为了改善用户在使用 API 时的体验。它还确保您的组织的 API 更易于维护和管理，因为现在已经建立了一个通用标准。它还允许团队围绕公认的 API 样式模式更好地协同工作，从而加快开发速度和可重用性。因此，为了确保一致性、可重用性、可维护性以及尝试集成和使用您的 API 的开发人员的良好体验，需要在您组织的所有 API 中确保通用的设计标准。这意味着组织不仅需要设定设计标准，还需要一种可靠的方法来执行这些标准，并确保每个使用 API 的人都了解这些设计要求。认识到这一需求，SwaggerHub 团队开发了一种新的 样式验证器集成，以确保您组织所有 API 的设计标准合规性。
确保良好 API 设计的更好方法
样式验证器可以作为集成添加到任何 API。对于不熟悉的人来说，集成是自定义的附加组件，可以扩展您在 SwaggerHub 上的 API 功能。然后可以自定义样式验证器集成以适应您的设计标准。可以从 SwaggerHub 编辑器的右上角将样式验证器添加到任何 API 版本。
了解如何使用样式验证器。使用样式验证器的好处很多，并且会对 API 的开发和使用产生直接的积极影响。使用样式验证器可以确保您的 API
提供良好的概览
在您潜在的 API 用户甚至开始学习如何针对您的 API 编写代码之前，他们需要了解您的 API 可以提供什么。样式验证器可以确保您的 API 具有最低级别的高级信息，使最终用户更好地了解您的 API 的作用。此信息由 API 合约的 description、license 和 contact 值定义。
设计用于加速开发
不同的团队使用不同的应用程序、技术堆栈和工具集来实现他们的 API。这可能是将合同挂接到 PhP 包中，将其连接到 API 管理平台，或将其链接到在 API 后运行的实现。样式验证器可以验证每个操作中的 operationId、summary、description 和 tag，以确保每个操作都与团队的工具集有正确的连接，并准确描述它应该做什么，以便不同的内部团队可以获得对该操作的预期目的的可见性、理解和接受。
验证器还可以通过仅允许全局模型而不允许局部模型，确保您的 API 开发允许更好地全局重用在 definitions 标记下定义的常见架构。
易于理解
一个设计良好的 API 将告诉用户确切需要哪些参数，并准确描述每个响应的含义。提供各种端点的参数和响应中的良好描述和示例是执行此操作的好方法。提供示例的目的是为用户提供一个即时的、相关的参考，说明他们应该输入什么样的参数以及他们应该期望的理想响应数据包。您可以确保所有模型属性都有示例，以便您的 API 合约的设计能够更好地理解请求-响应周期。
易于学习
一个设计良好的 API 将易于使用，并且经常使用它的开发人员可以快速记住其资源和相关操作。最快的方法是使您的路径、参数、模型和属性的命名保持一致。使用样式验证器，您可以确保您的 API 命名法遵循“underscore_case”或“camelCase”，以帮助您的用户轻松适应使用您的 API。
立即尝试样式验证器
样式验证器是组织确保其团队在接受的设计标准上保持一致，并且 API 已准备好投入生产的好方法。您可以在此处了解有关设置样式验证器的更多信息。如果您对任何其他集成或功能有建议，请在此处告知我们。 立即登录以亲自试用样式验证器。