OpenAPI 规范（中文版）介绍

简介

OpenAPI 规范（中文版）地址为 https://openapi.apifox.cn/，是对 OpenAPI 规范的简体中文翻译与说明文档。OpenAPI 3.0.0 是 OpenAPI 规范的第一个正式版本，由 SmartBear Software 捐赠给 OpenAPI Initiative，并于 2015 年从 Swagger 规范重命名为 OpenAPI 规范。本文档遵循 Apache License, Version 2.0 许可。

OpenAPI 规范（OAS）是定义一个标准的、与具体编程语言无关的 RESTful API 的规范。它使得人类和计算机都能在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。若遵循该规范定义 API，则可利用文档生成工具展示 API、用代码生成工具自动生成各种编程语言的服务器端和客户端代码，以及使用自动测试工具进行测试等。

主要内容结构

该中文版文档包含以下主要章节：

• 一、OpenAPI 规范：说明版本（3.0.0）及文档中关键词遵循的 RFC 约定。
• 二、介绍：规范的目标与价值。
• 三、术语定义：包括 OpenAPI 文档、Path 模板、Media Types、HTTP 状态码等。
• 四、规范：涵盖版本号规则、格式（JSON/YAML）、文档结构、数据类型、富文本格式、URL 的关联引用等。
• 五、数据结构：详细列出了 OpenAPI 对象、Info 对象、Contact 对象、License 对象、Server 对象、Components 对象、Paths 对象、Operation 对象等数十种规范定义的对象及其固定字段。
• 六、规范扩展
• 七、Security Filtering
• 八、Appendix A: Revision History

规范核心要点

版本与格式

• 版本号符合语义化版本 2.0.0，主版本号和次版本号标记特性变动，修订号表示错误修正；兼容 3.. 的文档须包含 openapi 字段标明版本。
• 文档是自包含的 JSON 对象，可用 JSON 或 YAML 格式编写；字段名均为小写，分为固定字段和模式字段。

数据类型

基于 JSON Schema Specification Wright Draft 00，支持 integer、long、float、double、string、byte、binary、boolean、date、dateTime、password 等原始类型及可选 format 修饰符。

文档结构

可以是单个文件或拆分为多个文件（使用 $ref 相互引用），根文档推荐命名为 openapi.json 或 openapi.yaml。

适用场景

• API 设计者：参照中文规范定义标准、语言无关的 RESTful API。
• 开发工具厂商：基于规范开发文档生成、代码生成、自动测试等工具。
• 中文开发者：在不接触源码的情况下，通过统一规范理解并对接各类 API 服务。