API Schema 定义了客户端和服务器之间交换数据的结构、类型和约束。它指定了端点、请求参数、响应结构以及其他细节，通过提供清晰的蓝图，让开发者能够理解如何有效地与 API 进行交互。API Schema 确保 API 的一致性、可靠性以及更易于维护。基本上，API 使不同的软件系统能够相互通信，它们允许各种应用程序彼此交互以共享数据和功能。API 定义了应用程序用于通信的方法和数据格式，充当翻译请求和响应的中介。
以下是我们将要讨论的主题：
目录
- 为什么需要它？
- API Schema 的类型
- OpenAPI
- RAML
- API Blueprint
- API Schema 的优势
为什么需要它？
API 对于构建和集成软件系统至关重要，它们能够：
- 使不同的系统协同工作。
- 允许第三方开发者扩展功能。
- 促进微服务架构的创建。
- 支持移动和 Web 应用程序的开发。
- 提高数据交换和功能集成的效率。
API Schema 的类型
- OpenAPI
- RESTful API Modeling Language (RAML)
- API Blueprint
OpenAPI
OpenAPI 规范（OAS）是定义 RESTful API 的标准。它允许人类和计算机在无需访问源代码或文档的情况下，发现和理解服务的功能。
语法：
OpenAPI 定义可以用 JSON 或 YAML 格式编写。
openapi: 3.0.0
info:
title: Sample API
description: A sample API to illustrate OpenAPI specification
version: 1.0.0
servers:
- url: https://api.example.com/v1
paths:
/users:
get:
summary: List all users
responses:
‘200‘:
description: A list of users
content:
application/json:
schema:
type: array
items:
$ref: ‘#/components/schemas/User‘
components:
schemas:
User:
type: object
properties:
id:
type: integer
name:
type: string
解释：
- Info Section（信息部分）
– openapi：OpenAPI 规范的版本。
– info：包含关于 API 的元数据，如标题、描述和版本。
- Servers Section（服务器部分）
– servers：定义 API 的基础 URL。
- Paths Section（路径部分）
– paths：定义 API 中可用的端点。
– /users：
– get：指定用于检索用户列表的 GET 方法。
– summary：操作的简要描述。
– operationId：操作的唯一标识符。
– responses：定义可能的响应。
– 200：表示成功的响应，并指定了内容类型和 Schema。
– /users/{id}：（注：此部分为文档结构说明中的隐含内容）
– get：指定用于通过 ID 检索单个用户的 GET 方法。
– summary：操作的简要描述。
– operationId：操作的唯一标识符。
– parameters：定义路径参数 id。
– responses：定义可能的响应。
– 200：表示成功的响应，并指定了内容类型和 Schema。
– 404：表示未找到用户。
- Components Section（组件部分）
– components：包含可重用的组件，例如 Schema。
– schemas：
– User：定义 User 对象的结构。
– type：指定 Schema 的类型（对象）。
– properties：列出 User 对象的属性。
– id：表示用户 ID 的整数。
– name：表示用户名称的字符串。
示例：
这里我们提供一个示例 YAML 格式的代码片段供参考。在这个 YAML 文件中，我们配置了 Open API 版本、标题、描述和版本信息。它还包含了带有内容类型、描述、HTTP 成功状态码等信息的路径。
openapi: 3.0.0
info:
title: Sample API
description: API description in Markdown.
version: 1.0.0
paths:
/users:
get:
summary: Returns a list of users.
responses:
‘200‘:
description: A JSON array of user names
content:
application/json:
schema:
type: array
items:
type: string
RAML
RAML 的全称是 RESTful API Modeling Language（RESTful API 建模语言）。RAML 是一种用于定义 RESTful API 的语言，它强调简洁性和可读性。它的目标是让 API 的设计、构建和使用变得更加简单。
语法：
RAML 定义是用 YAML 编写的。
#%RAML 1.0
title: Sample API
version: v1
baseUri: https://api.example.com/v1
mediaType: application/json
/users:
get:
description: Retrieve a list of users
（注：源文本在此截断，翻译也相应结束。）