当你请承包商从零开始建造一栋房子时,你期望他们交付最高水准的产品。
他们必须通过检查,遵守安全规范,并遵循项目商定的要求。在建筑行业偷工减料会带来严重后果。如果承包商多次偷工减料,他们的声誉可能会受到影响,人们就不会再请他们盖房子了。
在很多情况下,开发 API 的风险也同样高。
在构建 API 时,在将其发布到世界之前,创建出开发人员愿意使用并信任的、功能完善的最终产品至关重要。如果一切顺利,您会希望扩展您的 API 战略,但如果没有正确的流程,您可能会在一个有缺陷的基础上构建 API 程序,从而危及您的长期成功。
这都始于制定正确的计划。
步骤 1. 计划
就像承包商在新建筑动工前依赖蓝图一样,您也需要在 API 动工前制定好计划。不要让您的 API 成为 API 世界的“比萨斜塔”。
幸运的是,API 架构师也有蓝图。 OpenAPI 规范 就是其中之一。

OpenAPI 规范(前身为“Swagger 规范”)旨在为开发人员提供一种标准格式,以创建易于跨国界、技术栈和行业理解和使用的 API。
试图使用 OAS 与 API 集成的人员应该能够剖析并理解该 API 具体提供了什么。
就像蓝图为建筑的建造方式提供了清晰的指示一样,OpenAPI 规范也为 API 的构建方式提供了清晰的设计结构。
它让业务和技术利益相关者在任何开发开始之前就知道 API 将包含什么。这个过程被称为“设计优先”方法,其中 API 规范处于项目的最前沿。
从一开始就遵循 OpenAPI 规范,还可以让开发人员更快地开始构建 API,因为所有相关信息都已明确。
Swagger Editor 非常适合快速开始使用 OpenAPI 规范。它简洁、高效,并配备了许多开箱即用的功能,可帮助您设计和文档化 RESTful 接口。
- 该编辑器可在任何开发环境中工作,无论是本地还是网络端
- 在您编写时验证您的语法是否符合 OpenAPI 规范,并提供简洁的反馈和错误处理
- 可视化呈现您的 API 规范,并在定义 API 的同时与其交互
您可以免费下载开源的 Swagger Editor,或在 SwaggerHub 平台中访问该编辑器。
步骤 2. 构建
您已经花费了数小时、数天、数周、数月的时间来完善 API 的完美设计,现在终于到了开始构建的时候了。建造房屋时,拥有合适的团队和工具非常重要。构建 API 也是如此。有许多工具可以帮助您轻松高效地构建 API。
API 开发人员工具箱中始终应该有的工具之一,特别是在使用 OAS 进行构建时,就是 Swagger Codegen。Swagger Codegen 是另一个开源工具,它允许 API 开发人员通过生成 30 多种不同语言的样板代码来快速原型化 API。
步骤 3. 检查
这一步对成功至关重要。无论是住宅还是 API,您的项目都必须经过测试和检查,以发现错误和缺陷。在进行房屋检查时,通常有一套通过检查所需的要求。

有许多公司不测试他们的 API。同样,我们认为建筑检查员应该确保新房屋的建造达到标准。但现实中并非总是如此。
制作“足够好”的产品与“完美”的产品各有利弊。在软件领域,对某些人来说,发布第一个“足够好”的产品是完全可以接受的工作流程,但您应该确保它“足够好”到可以投入使用。
Swagger 希望确保所有 API 都“足够好”以通过可用性测试,这就是我们构建 Swagger Inspector 的原因之一。它是一个在线 API 测试工具,可以快速验证您的 API 是否按预期工作。
如果您确保交付的产品符合所有要求,那么从长远来看,您会做得更好。
步骤 4. 描述 和文档化
太棒了,您的项目完成了。
它已经通过了检查并获得了高分,现在您准备好将其推向市场,让所有人都能看到。您的第一反应可能是直接发布它,让您的 API 自己说话。请避免这样做!

文档化您的项目对最终用户来说非常重要。在我们的房屋示例中,您需要描述建筑面积、所在社区、卧室和浴室的数量、厨房中的电器类型、厨房中美丽的自然光等等。图片可能具有欺骗性,因此为潜在买家详细说明是关键。
您的 API 也是如此。编写文档很困难,但提供易于使用的 API 所带来的回报是物有所值的。引导他们了解各种选项,这样他们就不必进行假设,然后在假设不正确时感到沮丧。
明确说明您提供什么以及它如何工作,人们会更满意结果,因为他们不会觉得被误导了。
幸运的是,对于各地的开发人员来说, Swagger UI 允许您在没有任何实现逻辑的情况下可视化和交互 API 的资源。它从您的 OpenAPI 规范自动生成,可视化文档使其易于后端实现和客户端使用。它允许最终开发人员轻松地交互并尝试您的 API 公开的每一个操作,以便于使用。请在此处查看其工作方式 。
步骤 5. 推向市场

您的成品已经过测试和检查,并准备好向公众展示!您通过创建了一个基础坚固且文档齐全的产品,使自己处于有利地位,这样任何看到它的人都会清楚地知道它包含了什么。
无论是建造房屋还是 API,都要创造出令您自豪的东西。发布能让人眼前一亮的东西。这是您创造出色事物的机会,所以请花时间把它做好。
准备好开始构建了吗?
Swagger 助您一臂之力。 立即使用 Swagger 工具开始构建
构建 API 的其他资源