无需登录 数据私有 本地保存

Swagger 编辑器轻量版 - 在线编写 OpenAPI 规范

API 开发工具 OpenAPI Swagger YAML 编辑器
33
0
0
0

术语表

OpenAPI 规范

OpenAPI 规范（OpenAPI Specification，简称 OAS）是一种用于描述 RESTful API 的标准格式。它由 OpenAPI Initiative 维护，前身是 Swagger 规范。OpenAPI 规范使用 YAML 或 JSON 格式定义 API 的结构、端点、参数、响应、认证方式等信息。当前主流版本是 OpenAPI 3.0（最新为 3.0.3）和 OpenAPI 3.1。OpenAPI 规范是 API 设计优先（Design-First）方法论的基础，支持 API 文档自动生成、客户端 SDK 生成、服务器桩代码生成和自动化测试等场景。

Swagger

Swagger 最初是由 SmartBear Software 开发的一套 API 开发工具集，包括 Swagger Editor、Swagger UI 和 Swagger Codegen 等组件。2015 年，SmartBear 将 Swagger 规范捐赠给 OpenAPI Initiative，更名为 OpenAPI 规范。在日常使用中，Swagger 一词仍被广泛用来指代 OpenAPI 规范及相关工具。Swagger Editor 是一个在线编辑器，用于编写和预览 Swagger/OpenAPI 规范文档；Swagger UI 则将 OpenAPI 规范渲染为交互式的 API 文档页面。本工具是一个轻量版的 Swagger 风格编辑器，专注于核心的编辑和预览功能。

OpenAPI 3.0 与 2.0 的区别

OpenAPI 3.0 相较于 2.0 版本进行了重大改进：首先，3.0 引入了 requestBody 关键字来替代 2.0 中的 body 参数，使请求体的定义更加清晰；其次，3.0 新增了 oneOf、anyOf、allOf 等组合模式，增强了数据模型的表达能力；第三，3.0 改进了响应定义，支持 content 关键字来描述不同媒体类型的响应；第四，3.0 引入了 links 和 callbacks 等高级功能；第五，3.0 的安全方案定义更加灵活和标准化。建议新项目使用 OpenAPI 3.0 或更高版本，旧项目可以考虑迁移到 3.0 以获得更好的工具支持。

YAML 格式

YAML（YAML Ain't Markup Language）是一种人类可读的数据序列化格式，广泛用于配置文件和数据交换。YAML 使用缩进来表示层级关系，使用冒号分隔键值对，使用井号添加注释。与 JSON 相比，YAML 的语法更加简洁，不需要引号（除非值中包含特殊字符）和花括号。YAML 是编写 OpenAPI 规范的推荐格式，因为它提高了文档的可读性和可维护性。编写 YAML 时需要注意：缩进必须一致（推荐使用两个空格），不能使用 Tab 字符，键值对之间的冒号后面需要有一个空格。

paths 对象

paths 对象是 OpenAPI 规范中最核心的部分，定义了 API 的所有端点。paths 对象的键是 URL 路径（如 /users、/users/{id}），值是 Path Item 对象。Path Item 对象包含一个或多个 HTTP 方法（get、put、post、delete、options、head、patch、trace）对应的 Operation 对象。每个 Operation 对象定义了该操作的摘要（summary）、描述（description）、操作 ID（operationId）、参数（parameters）、请求体（requestBody）、响应（responses）、安全方案（security）等。URL 路径中可以使用花括号包裹的路径参数（如 {id}），用于传递动态值。

components/schemas

components/schemas 是 OpenAPI 规范中用于定义可复用数据模型的部分。在 schemas 中定义的数据模型可以在整个 API 规范中通过 $ref 关键字引用，避免重复定义。每个 schema 可以定义对象的属性（properties）、数据类型（type）、格式（format）、必填字段（required）、验证规则（如 minLength、maximum 等）等。例如，可以定义一个 User schema 包含 id、name、email 等属性，然后在多个端点的请求体和响应中引用这个 schema。这不仅减少了代码重复，还确保了数据模型在各处的一致性。

请求体（requestBody）

requestBody 是 OpenAPI 3.0 中用于定义请求体的关键字。它包含描述（description）、是否必需（required）以及内容（content）等字段。content 字段是一个映射，键是媒体类型（如 application/json、application/x-www-form-urlencoded），值是 Media Type 对象，其中包含 schema（数据模型）和 examples（示例数据）。requestBody 替代了 OpenAPI 2.0 中的 body 和 formData 参数，使请求体的定义更加统一和清晰。对于文件上传场景，可以使用 multipart/form-data 媒体类型，并将 schema 的类型设为 string，格式设为 binary。

$ref 引用

$ref 是 JSON Schema 中的关键字，用于引用其他位置定义的 schema。在 OpenAPI 规范中，$ref 通常用于引用 components/schemas 中定义的数据模型。$ref 的值是一个 JSON Pointer，指向目标 schema 的路径。例如，$ref: '#/components/schemas/User' 引用 components/schemas 中名为 User 的 schema。使用 $ref 可以实现数据模型的复用，减少重复定义，同时确保同一数据模型在 API 规范的不同位置保持一致。当数据模型需要修改时，只需修改定义处，所有引用处会自动生效。

Operation 对象

Operation 对象描述了 API 中的一个具体操作。它包含多个字段：tags 用于分类和分组操作；summary 是操作的简短描述；description 是操作的详细描述；operationId 是操作的唯一标识符，用于代码生成；parameters 定义路径参数、查询参数和请求头；requestBody 定义请求体；responses 定义各种状态码对应的响应；callbacks 定义回调操作；deprecated 标记操作是否已弃用；security 定义该操作所需的安全方案。Operation 对象是 OpenAPI 规范中最常用的对象之一，几乎每个 API 端点都会包含一个或多个 Operation 对象。

安全方案（Security Schemes）

安全方案定义了 API 的认证和授权方式。OpenAPI 3.0 支持四种类型的安全方案：apiKey 类型表示 API 密钥认证，密钥可以通过请求头、查询参数或 Cookie 传递；http 类型表示 HTTP 认证，支持 Basic、Bearer 和 Digest 等方案；oauth2 类型表示 OAuth 2.0 认证，支持多种授权流程；openIdConnect 类型表示 OpenID Connect 认证，基于 OAuth 2.0 并添加了身份层。在 components/securitySchemes 中定义安全方案后，可以在全局或单个操作中引用。正确的安全方案定义有助于客户端正确实现认证逻辑。

Media Type 对象

Media Type 对象描述了请求或响应中的内容格式。它包含 schema 字段定义数据结构，example 字段提供单个示例，examples 字段提供多个命名示例，encoding 字段指定编码方式。在 requestBody 的 content 和 responses 的 content 中都会使用 Media Type 对象。常见的媒体类型包括 application/json（JSON 数据）、application/xml（XML 数据）、application/x-www-form-urlencoded（表单数据）、multipart/form-data（多部分表单数据，用于文件上传）、text/plain（纯文本）等。正确设置媒体类型对于 API 的正确解析和处理至关重要。

🔧 相关工具