WHAT - OpenAPI 规范和开放 API

一、OpenAPI 规范

OpenAPI 是一种用于定义和描述 API（应用程序编程接口，Application Program Interface）的标准规范。它最初由 Swagger 项目提出，现在由 OpenAPI Initiative 进行维护和发展。OpenAPI 的核心目标是通过一种统一的、可读的格式来描述 RESTful APIs，便于开发者和系统之间进行交互和理解。

主要特点

1. API 文档标准化：OpenAPI 使用 JSON 或 YAML 格式来描述 API 的端点（endpoints）、请求和响应的格式、参数、认证方式等内容。

2. 工具支持：由于 OpenAPI 的标准化，很多工具可以自动生成 API 文档、SDK、测试用例，甚至可以通过 OpenAPI 文件来自动搭建 Mock 服务器。

3. 增强开发协作：API 提供者和使用者通过查看 OpenAPI 文档，可以清楚地知道 API 的行为和要求，从而减少沟通成本和误解。

主要元素

• Paths: API 的具体路径，如 /users、/orders/{id} 等。
• Operations: 每个路径下的请求操作，如 GET、POST、PUT、DELETE。
• Parameters: 请求中的参数，比如 URL 中的查询参数或路径参数。
• Responses: API 调用的响应，包括状态码（200、404 等）和响应数据的结构。
• Authentication: 对 API 的认证机制说明，如 API Key、OAuth 等。

一个简单的 OpenAPI 示例（YAML 格式）

openapi: 3.0.0
info:title: Sample APIversion: 1.0.0
paths:/users:get:summary: 获取所有用户responses:'200':description: 成功响应content:application/json:schema:type: arrayitems:type: objectproperties:id:type: integername:type: string/users/{id}:get:summary: 获取单个用户parameters:- name: idin: pathrequired: trueschema:type: integerresponses:'200':description: 成功响应

OpenAPI 的优势

• 自动化文档生成：可以根据 OpenAPI 定义自动生成直观的 API 文档，例如 Swagger UI、Redoc。
• 代码生成：可以根据 OpenAPI 定义自动生成 API 客户端或服务器端代码，减少重复开发工作。
• 一致性：团队成员可以使用统一的 API 描述，确保开发和使用 API 的一致性。

常见应用

• API 文档：通过 OpenAPI 定义生成交互式的 API 文档，如 Swagger UI。
• API 设计：在开发之前，团队可以先设计 API，并通过 OpenAPI 文件来分享和讨论。
• 测试与验证：基于 OpenAPI 定义的 Mock 服务和测试工具可以帮助验证 API 行为是否符合设计。

总之，OpenAPI 是现代 API 开发中非常常用的工具和标准，用于帮助开发者更高效、准确地构建和使用 APIs。

二、开放 API

当前服务提供给第三方使用的 API 通常被称为 开放 API（Open API） 或 公共 API（Public API）。这种 API 的设计初衷是允许外部开发者、企业、或者应用程序访问服务提供者的某些功能或数据，从而进行集成、扩展和创新。

开放 API 的特点

1. 公开可用：任何开发者或组织都可以注册并使用这些 API，只要符合服务提供者的使用条款和规定。

2. 标准化接口：通过标准化的 HTTP 方法（如 GET、POST、PUT 等）和数据格式（通常是 JSON 或 XML）来访问和操作资源。

3. 认证和授权：通常需要使用 API Key、OAuth 等方式来认证和授权，以确保只有合法的用户才能访问 API。

4. 开发者支持：开放 API 通常伴随有详细的文档、SDK（软件开发工具包）、示例代码以及其他开发者资源，以便外部开发者更容易集成和使用。

开放 API 的常见用途

• 应用集成：其他开发者或公司可以通过 API 将自己的应用与服务提供者的系统集成，例如支付系统集成、社交媒体登录等。
• 创新与扩展：第三方开发者可以基于开放 API 构建新的功能或应用，扩展原有服务的使用场景。
• 数据共享：提供商可以通过 API 向外部提供数据访问权限，方便数据共享或分析。

开放 API 的例子

• Google Maps API：允许第三方在他们的应用中集成 Google 地图服务，比如在一个电商网站上显示店铺位置。
• Twitter API：外部开发者可以通过 Twitter API 读取和发布推文。
• Stripe API：开发者可以通过 Stripe API 集成支付功能，处理信用卡支付等操作。

相比之下，如果 API 是为内部使用或特定合作伙伴而设计的，它可能会称为 私有 API（Private API） 或 合作伙伴 API（Partner API）。

以下是一些常见的开放 API的示例及其访问地址，供你参考：

1. Google Maps API

• 功能：提供地图显示、地址检索、路线规划等功能。
• API 文档：Google Maps API 文档
• 访问地址：https://maps.googleapis.com/maps/api

2. Twitter API

• 功能：提供访问 Twitter 数据的接口，例如推文检索、用户数据、发布推文等。
• API 文档：Twitter API 文档
• 访问地址：https://api.twitter.com

3. GitHub API

• 功能：允许开发者访问 GitHub 数据，如仓库、Issues、Pull Requests 等。
• API 文档：GitHub REST API 文档
• 访问地址：https://api.github.com

4. Stripe API

• 功能：提供支付处理、订阅管理、发票、退款等功能。
• API 文档：Stripe API 文档
• 访问地址：https://api.stripe.com

5. OpenWeather API

• 功能：提供全球天气数据，实时天气、天气预报等。
• API 文档：OpenWeather API 文档
• 访问地址：https://api.openweathermap.org

6. Spotify API

• 功能：提供对 Spotify 数据的访问，例如播放列表、歌曲、专辑信息等。
• API 文档：Spotify API 文档
• 访问地址：https://api.spotify.com

7. NASA API

• 功能：提供对 NASA 数据的访问，例如图片、行星、天气等空间相关的数据。
• API 文档：NASA API 文档
• 访问地址：https://api.nasa.gov

你可以通过这些 API 提供的文档获取到 API Key（通常需要注册）后，结合 API 访问地址使用这些开放 API。

三、两者区别

OpenAPI 和 开放 API 是两个相关但不同的概念：

1. 开放 API（Open/Public API）

• 定义：开放 API，或公共 API，是一种通过互联网向外部开发者、组织、或公众开放的接口。其目的是允许第三方访问应用或服务的某些功能或数据，从而实现集成、创新或扩展。
• 使用场景：开放 API 通常用于为外部提供服务，例如允许第三方应用访问某个服务的用户信息、支付系统、地图功能等。
• 例子：
  • Google Maps API
  • Twitter API
  • Stripe API
• 特点：公开可用、标准化的接口，通常需要认证授权（如 API Key 或 OAuth）。

2. OpenAPI（OpenAPI Specification, OAS）

• 定义：OpenAPI 是一种 标准，用于描述 RESTful API 的格式。它是一个定义规范，帮助开发者使用一种标准化的方式描述 API 的端点、请求/响应格式、参数等。
• 主要作用：OpenAPI 本身不提供 API，它提供了一种标准化的文档格式，用于描述和设计 API。使用 OpenAPI 描述的 API 文档可以被工具解析，生成客户端代码、服务器代码，甚至可以自动生成 API 文档。
• 使用场景：开发团队使用 OpenAPI 规范来定义 API，使得不同开发者或团队能够更清晰地理解和集成 API，也可以用于自动生成文档、测试、模拟请求等。
• 特点：
  • OpenAPI 描述了 API 的行为和结构，包括端点、请求方法、参数、响应等。
  • 常与 Swagger、Postman 等工具结合使用来生成文档、测试 API。

总结区别

• 开放 API 是一种服务，指的是面向公众开放、可供第三方使用的 API。
• OpenAPI 是一个标准或规范，帮助开发者描述 API 的结构和行为，以便进行文档化、生成客户端代码或测试 API。

简单来说，开放 API 是一个可使用的接口，而 OpenAPI 是用来描述这些接口的一种方式。