什么是API定义？

成熟的 API 经济最显著的优势之一在于无需从零开始构建所有功能。API 初期，开发人员往往需要自己添加所需功能，并解决如何实现的具体问题。这种方式不仅效率低下，还大大限制了其他开发者使用或集成该 API 的可能性。

API 定义几乎彻底解决了这些问题。API 定义，也称为 API 规范，不仅是 API 的蓝图，还是包含所有描述其功能的元数据的详细记录。

了解 API 定义的概念

API 定义是 API 结构和操作方式的图表，明确指定了 API 的端点。它定义了接收什么类型的请求和响应，以及期望的输入输出数据类型。API 定义还包括可能的额外参数，并且指定了 API 调用所需的身份验证方式。API 定义充当 API 提供者和消费者之间的合同，确保双方清晰了解 API 的工作原理。

API 定义对 API 开发和 API 文档的生成至关重要，同时也是 API 集成的关键，因为它在入门阶段发挥着重要作用。通过 API 定义，开发人员可以了解如何使用 API，而无需深入解析源代码。清晰明了的 API 规范还能确保 API 的实现一致性与可靠性。

OpenAPI 是目前最流行的 API 定义行业标准规范，虽然它并非唯一的选择。多年来，已经制定了多种不同的 API 规范，每种规范都有其特定的优缺点。

API 定义的历史

在 API 规范出现之前，API 的开发完全依赖于开发者的随意操作，且缺乏一致性。API 文档往往不完整，导致 API 集成变得困难、低效且令人沮丧。这种情况还使得技术知识相对较少的用户无法轻松使用 API，从而大大限制了其吸引力。

Swagger 的崛起

随着 Swagger 的出现，API 定义在 2010 年开始得到广泛关注。Swagger 由 Tony Tim 创建，旨在为 API 的记录、定义和交互提供一个全面的解决方案。为了实现这一目标，Swagger 采用了一种标准化的格式，以机器可理解的方式描述 RESTful API。Swagger 的普及推动了自动化 API 文档生成、SDK 生成以及服务器存根的快速发展。

Swagger 包含三个主要组成部分。首先是 API 规范本身，通常以 JSON 或 YAML 文件的形式存在。接着是 Swagger UI，它允许开发人员通过浏览器与 API 进行交互。最后是代码生成工具，用户可以基于 API 定义生成自己的 API 文档和客户端库。

OpenAPI 规范的兴起

2015 年，SmartBear 将 Swagger 捐赠给 Linux 基金会，Swagger API 定义转变为 OpenAPI 规范（OAS）。这一转变由 OpenAPI Initiative 发起，旨在使 API 行业更加中立、开源，并避免依赖单一供应商。微软、谷歌等全球顶尖科技公司加入了这一倡议，成为推动 OpenAPI 合法化的重要力量。

OpenAPI 规范继承了 Swagger API 规范的基本元素，并引入了多个关键组件。最重要的是，它标准化了 API 端点的描述方法、请求和响应的处理方式以及身份验证方法。这一标准化进程促进了 API 的快速发展，使得现代的 API 行业得以蓬勃发展。

OpenAPI 继续扩展其应用场景，并见证了新的用例的不断发展。例如，围绕 Arazzo 规范的进展使 OpenAPI 能够描述复杂的 API 工作流及其相互关联。

API 定义的好处

API 规范在很大程度上决定了 API 在现代软件开发中的角色。以下是使用 API 规范的几个主要好处：

一致性和标准化
API 规范验证 API 的各个方面，确保其定义规范且统一。这种标准化有助于开发人员快速理解如何与 API 交互，缩短学习曲线并减少错误。
改善协作
API 定义使不同团队之间的协作变得更加顺畅。后端开发人员可以根据 API 定义实现 API，而前端开发人员可以基于相同的规范进行 UI 界面开发。
自动化文档
API 定义使得自动化 API 文档生成成为可能。这样的文档通常是交互式的，允许开发人员直接在文档中测试 API 端点。
更轻松的维护和更新
当 API 需要更新或扩展时，良好的 API 定义有助于理解 API 的结构，从而更容易规划相应的更改。这有助于确保新版本与旧版本兼容，并能保持稳定的 API 版本控制策略。
增强测试和验证
API 定义常常用于生成模拟服务器和客户端 SDK，支持彻底的 API 测试。此外，API 规范可用于验证请求和响应，确保它们符合既定架构要求。
安全与合规性
清晰的 API 定义有助于界定和实施安全策略，并确保 API 遵循行业标准和最佳实践，以满足所需的安全性和隐私合规要求。

比较不同的 API 规范

现在，让我们详细比较一些最流行的 API 规范，以便更好地了解它们的异同。

OpenAPI

OpenAPI 规范（OAS），前身为 Swagger，是目前最流行且广泛采用的 API 定义之一。它允许开发人员以机器可读的格式定义 API 结构，从而生成文档、客户端 SDK 和服务器存根。

RAML

RESTful API 建模语言（RAML）是另一种 API 规范格式，强调可读性和简单性，使人类更容易理解和使用。RAML 文件采用 YAML 格式，YAML 是一种易于阅读的数据序列化格式。

API Blueprint

API Blueprint 是一种 API 规范语言，使用 Markdown 格式定义 API。它的重点是简洁性和协作性，使得编写和共享 API 文档变得更加方便。

规范	介绍	开发者	主要特点
Swagger/OpenAPI	2010 年发布，最流行的 API 规范之一	谭东尼	JSON/YAML 格式、交互式文档、代码生成
OpenAPI 规范 (OAS)	2015 年，OpenAPI 计划（Linux 基金会）主导	OpenAPI 计划	标准化 API 描述，社区驱动，提高灵活性
RAML	–	MuleSoft	API 描述简洁、简单、易用
API Blueprint	–	–	基于 Markdown 的、人性化的语法

各规范的比较

特征	Swagger/OpenAPI	RAML	API Blueprint
文档生成	出色	好的	好的
代码生成	支持	支持	有限
可读性	中等	高	高
采用程度	高	中等	低
可扩展性	高	中等	中等

深入了解行业标准：OpenAPI

OpenAPI 被广泛认为是当前 API 规范的行业标准。它不仅能够提供全面的 API 文档，还配套了多种工具用于代码生成和测试，极大地提升了开发效率和集成度。

主要特点

详细文档：OpenAPI 能够全面描述 API 的各个方面，包括端点、请求和响应格式、参数以及身份验证方法。
交互式文档：借助 Swagger UI 等工具，OpenAPI 可以生成交互式文档，允许用户直接在浏览器中测试 API 端点。
广泛的工具支持：OpenAPI 提供丰富的工具支持，包括代码生成器、API 测试工具以及验证框架，帮助开发人员更高效地开发和维护 API。
社区和生态系统：OpenAPI 拥有一个庞大且活跃的开发者社区，其工具和库的生态系统在所有 API 规范中最为丰富。

使用案例

OpenAPI 特别适用于需要详细文档和全面工具支持的复杂 API，特别是需要严格维护 API 标准的大型企业应用和服务。

OpenAPI 示例

openapi: "3.0.0"

info:

  title: Simple API overview

  version: 2.0.0

paths:

  /:

    get:

      operationId: listVersionsv2

      summary: List API versions

      responses:

        '200':

          description: |-

            200 response

          content:

            application/json:

              examples:

                foo:

                  value:

                    {

                      "versions": [

                        {

                            "status": "CURRENT",

                            "updated": "2011-01-21T11:33:21Z",

                            "id": "v2.0",

                            "links": [

                                {

                                    "href": "http://127.0.0.1:8774/v2/",

                                    "rel": "self"

                                }

                            ]

                        },

                        {

                            "status": "EXPERIMENTAL",

                            "updated": "2013-07-23T11:33:21Z",

                            "id": "v3.0",

                            "links": [

                                {

                                    "href": "http://127.0.0.1:8774/v3/",

                                    "rel": "self"

                                }

                            ]

                        }

                      ]

                    }

类型规格（TypeSpec）

另一种用于描述 API 的格式是 TypeSpec。TypeSpec 由微软设计，旨在通过类似代码的语法简化 API 设计，从而提高开发人员的效率和一致性。

主要特点

类代码语法：与 TypeScript 类似的语法，使开发人员更直观易懂。
设计优先方法：支持在实现之前创建 API 设计，注重规划和设计的前瞻性。
集成：TypeSpec 可与 OpenAPI 等工具配合使用，确保更广泛的兼容性。
可重用代码：支持将 API 指南进行编码和重用，提升开发效率。

使用案例

TypeSpec 是 OpenAPI 的轻量级、灵活替代方案，特别适合那些希望利用设计优先方法和可重用组件的开发人员和项目。

TypeSpec 示例

namespace ExampleService {

  @service

  interface ExampleAPI {

    @get("/items")

    @returns(ItemList)

    getItems(): ItemList;



    @post("/items")

    @body(Item)

    @returns(Item)

    createItem(item: Item): Item;

  }



  model Item {

    id: string;

    name: string;

    description?: string;

  }



  model ItemList {

    items: Item[];

  }

}