因此，您着手构建一个很棒的 API...太棒了！或者您已经有一个 API...那就更好了！
为您的 API 创建定义是 API 开发中一个重要步骤，但经常被忽视。API 定义（有时称为 API 规范或描述格式）旨在提供一种机器可读的 API 描述格式。它们是与语言无关的，因此无论您选择哪种语言都可以从中受益。
如今，最常用的 API 定义是OpenAPI 规范。OpenAPI 规范 (OAS) 基于原始的 Swagger 规范，定义了 API 的 RESTful 标准。OAS 定义映射 API 的资源和操作。
本文描述了创建定义的优点，以及一些可以使您的生活更轻松的工具。
为何创建定义
您的 API 定义可用于
- 帮助内部人员理解 API 并就其属性达成一致：这对我上一家公司来说非常强大。API 定义允许像 Swagger UI 这样的文档工具可视化 API。我们使用 Swagger UI 可视化我们所有的内部 API，以便开发人员可以快速轻松地使用上游和下游服务。SwaggerHub 具有团队和企业级功能，可以设计、查看和协作处理 API。
- 帮助外部人员理解 API 及其功能：同样，Swagger UI是一个常用的文档可视化工具，我个人最喜欢的是Marvel API。还有其他很棒的文档解决方案将 API 定义文件作为其输入，例如ReDoc、ReadMe和Slate。
- 为您的 API 创建测试：您的 OAS 定义提供了一个契约，描述了当有人调用您的 API 时响应是什么样的。这个契约可以重新用于创建测试用例。这可以大大减少团队测试 API 所需的设置量。您可以使用 ReadyAPI 从 API 定义创建功能测试、负载测试、运行安全扫描以及虚拟化您的 API，您可以通过导入您的 API 定义来启动所有操作
- 生成实现代码和 SDK：除了生成文档外，OpenAPI 定义还可用于通过创建实现代码和 SDK 来加速开发。API 定义文件可以导入到许多不同的工具中，例如 Swagger Codegen 和 SwaggerHub。它们可以用许多不同的语言创建代码，例如 Java、Scala 和 Ruby。创建实现代码，这样您就不必从头开始编写 API 代码。
- 使您的 API 上线：像Amazon API Gateway、Azure、Apigee或Google Cloud之类的 API 网关都使用 API 定义来创建实时 API。
- 监控您的 API：理想情况下，您希望在客户注意到之前知道您的 API 是否有问题。如果将您的定义导入到像 Alertsite 这样的工具中，则可以自动监控 API。
您的 API 定义应作为您 API 的真实来源。它可用于实现 API、记录 API，并为确保您的 API 成功所需的工具提供支持。
创建 API 定义
既然我已经描述了为什么要创建定义，我将描述一些关于如何创建定义的方法。您有几个选择
- 首先设计您的 API，并选择性地从定义创建实现代码
- 调用您的 API 并使用这些请求创建定义
- 让您的代码生成定义
1. 首先编写定义（然后实现）
“设计优先”方法提倡在编写任何代码之前首先编写 API 定义。这是一种相对较新的方法，但正在迅速流行起来。在编写任何代码之前发现设计问题比在实现完成后发现问题更有效。
像SwaggerHub这样的基于团队的工具提供了设计和协作处理 API 的强大功能。您可以设置管理员级别的权限，允许用户对定义进行更改和合并，并且您会获得一个可视化编辑器。您还可以阅读有关如何创建符合 OpenAPI 的定义并使用文本编辑器创建 YAML 文件的信息。如果您需要其他工具，并且不想使用 SwaggerHub，则可以使用Swagger-Editor进行编辑，使用Swagger-UI进行记录，以及使用Swagger-Validator验证您的定义。
创建定义后，可以为 API 创建实现代码。SwaggerHub 使创建实现代码（服务器存根）变得容易。您还可以使用这个开源库 Swagger-Core执行相同的操作。您需要添加任何无法仅通过定义描述的业务逻辑。您可以设置流程，以便在 API 定义更改时创建实现代码。
2. 使用 Swagger Inspector 从 API 调用创建定义
如果您已经实现了您的 API（至少部分实现），您可以简单地从 Swagger Inspector 向您的 API 发出请求。
Swagger Inspector 可以执行 API 请求、验证响应并创建 OpenAPI 定义。您可以通过调用端点、选择它们并单击“创建 API 定义”来为现有 API 创建文档。
这会自动为您选择的端点生成 OpenAPI 文件，从而节省宝贵的开发时间。我们将定义免费存储在 SwaggerHub 中，您可以立即访问 API 的文档。您还可以导出该文件并创建客户端 SDK。
这种方法会生成 API 的快照，但如果你的 API 没有太大变化，那就没关系！这可能是创建 API 定义最快的方法，也是我最喜欢的方法，因为它使用了我们的新产品 Swagger Inspector。如果你有任何建议，请务必在右下角的窗口中留下反馈！
3. 代码生成的定义
有几个项目可以帮助你从代码生成 API 定义。我们在 SmartBear 花费最多时间的项目是 Swagger-Core，它可以与 Java 7 或 8 以及 maven 3.0.4+ 一起使用。SmartBear 也为 Scala 和 Javascript 项目做出了贡献，这些项目可以根据你的代码创建定义。如果你使用不同的语言，很可能通过稍加搜索就可以找到一个库。例如，SwashBuckle 是一个 .NET 库，它也可以做同样的事情。
从代码创建定义是一个绝佳的方法。它可以确保你的定义与你的实现一致。但这也会带来一些挑战。例如，你需要确保定义具有人性化的描述和示例。如果你有专门的技术作家，他们应该与你的开发人员密切合作，以使这种方法顺利进行。
无论你选择使用哪种方法，我们都希望这些技巧能帮助你创建一个出色的 API！