所以您已经着手构建一个出色的 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！