OpenAPI 官方规范文档

OpenAPI 规范（OpenAPI Specification，OAS）是 Linux 基金会旗下的开放标准，用于描述 HTTP API 的接口规范。它定义了一种与编程语言无关、标准化的接口描述格式，帮助开发者和计算机系统在不依赖源码或额外文档的情况下，发现并理解 API 的功能。最新版本为 v3.2.0（2025 年 9 月发布），更新了数据模型、序列化规则和媒体类型支持等内容。

该规范文档详细介绍了 OpenAPI 对象的各个字段，包括信息对象（Info Object）、服务器对象（Server Object）、路径对象（Paths Object）、操作对象（Operation Object）等。它支持 JSON 和 YAML 两种格式，并全面兼容 JSON Schema 标准（特别是针对 OAS 3.1 及更高版本）。文档还涵盖了安全方案、参数序列化、媒体类型编码、链接和回调等高级特性。

主要功能：描述 API 的端点、请求参数、响应数据；支持多种认证方式（如 OAuth2、API Key）；提供示例和扩展机制；定义服务器变量和基础 URL。适用于 RESTful API 的设计、文档生成、客户端 SDK 自动生成、测试和集成。

适用人群：API 开发者、架构师、测试工程师、API 文档撰写者。

使用方式：以 JSON 或 YAML 格式编写 OpenAPI 描述文件，可使用 Swagger Editor、Swagger UI、Postman、Apifox 等工具加载和展示。

注意事项：遵循规范的版本兼容性，3.2.0 有部分破坏性变更，需参考迁移指南。实时规范请以 spec.openapis.org 为准。