如果想实现一个api管理的功能，类似于postman，那就跳不过 open Api 规范，作为页面都认可的接口设计规范，主要约定了接口文档的格式和规范，也是为了方便不同平台之间实现api文档的互通。今天我们来讨论一下openAPI相关的知识：
1.什么是OpenAPI
1.1 什么是API
Application Programming Interface（API）定义了** 两个软件之间允许的交互，就像两个人之间说话一样，api就是两个软件之间沟通的语言。
所以API 由可能调用的方法（发出的请求）列表、它们的参数、返回值以及它们需要的任何数据格式（除其他外）组成。API 可以是本地的，也可以远程的，比如打开抖音那一刻，抖音软件已经向后端的服务器发送了好多个api请求。
使用 API 是计算机科学中的日常实践，因为它们的好处是毋庸置疑的。只列出最突出的：
- API 提供信息隐藏：API 的任何一方（调用者和实现者）都不知道另一方的实现细节。只要双方都遵守 API的规范，就可以根据需要进行更改，而对方甚至不会注意到。
- API 也称为合约，因为它们被认为是牢不可破的：提供api的一方承诺不会更改其 API 并在未来几年继续遵守它。有了这一承诺，其他开发者就可以开始开发自己的应用。
所以总结一下，api是软件之间沟通的语言，调用api就是软件之间的通话。
1.2 什么是api文档
那api文档就顺势很好理解了，api是软件之间的语言，类似于A和B之间说话，那C也想和B说话那怎么办呢，那C也要知道和B沟通要怎么说，说什么，这个时候就需要把和B沟通的方式和内容记录下来，方便其他有需求的都能使用，这就是API文档。
它的内容包括：
- 请求的地址
- 请求的方法
- 请求的参数
- 返回的数据类型
- 各种示例
- ...
- 服务的地址
最终达到C可以直接看这个文档，就能够实现和B进行沟通的目的。
1.3 OpenApi规范
那什么又是OpenApi规范呢？如果读到上面的内容，你会发现一个问题，上面api的文档包括了好多内容，有些可能是非必填的，也像我们的方言一样，我可以有自己的表述习惯，这样就带来了一个问题：
1000个软件就有1000个api文档的写法
这个结果在单个项目内部没有大的问题，但是如果涉及到跨软件或者团队之间的合作，就很不方便了，所以此时就需要有一个大家都公认的规范，来约束应该如何去撰写和实现api，使用者也依照规范来读取，这样大大降低了合作的成本。
而OAS 由 OpenAPI Initiative ( OAI ) 维护、发展和推广，该组织是一个由行业专家组成的联盟，在 Linux 基金会的保护下拥有开放的治理结构。这意味着所有会议和决策都是公开的，任何人都可以提议和讨论对美洲国家组织的变更。
但是需要注意的是，OpenApi很多时候指的的是它规范，很多时候基于OpenApi衍生的工具也很多，可能包括文档的生成，调试等，本文接下来主要讨论OpenApi的规范。
2.使用OpenAPI有什么优势
这里的OpenApi指的是基于openApi 规范设计的一系列的工具，使用这个工具有啥优势：
- 描述验证和Linting：检查描述文件在语法上是否正确，并符合特定版本的规范和团队的其他格式准则。
- 数据验证：在开发期间和部署后，检查流经API（双向）的数据是否正确。
- 文档生成：始终能够基于机器可读的描述来创建传统的人类可读文档。
- 代码生成：用任何编程语言创建服务器和客户端代码，使开发人员不必执行数据验证或编写SDK粘合代码。
- 图形化编辑：允许使用GUI轻松创建描述文件，而不是手动键入。
- Mock 服务器：创建假服务器，提供示例响应，您和您的客户可以在编写一行代码之前开始测试。
- 安全分析：在API设计阶段发现可能的漏洞，而不是在代码开发发布之后。
除此之外，OpenAPI规范还为提供了：
- 开源的规范：任何人都可以对规范的未来方向进行提议
- 最发达的工具生态系统：作为上一句话的直接结果，OpenAPI提供了大量的工具来使用它。只需快速查看一下OpenAPI Tooling
- 一种机器和人类都可读的格式：尽管手工编写OAD不是最方便的方法（请参阅最佳实践），但它们是纯文本文件，在需要调试时可以轻松浏览。
3.规范详解
说了这么多，大家也对openApi有了大致的了解，openApi自2011年发布之后版本如下：
| Version | Date | Notes |
|---|---|---|
| 3.1.0 | 2021-02-15 | Release of the OpenAPI Specification 3.1.0 |
| 3.1.0-rc1 | 2020-10-08 | rc1 of the 3.1 specification |
| 3.1.0-rc0 | 2020-06-18 | rc0 of the 3.1 specification |
| 3.0.3 | 2020-02-20 | Patch release of the OpenAPI Specification 3.0.3 |
| 3.0.2 | 2018-10-08 | Patch release of the OpenAPI Specification 3.0.2 |
| 3.0.1 | 2017-12-06 | Patch release of the OpenAPI Specification 3.0.1 |
| 3.0.0 | 2017-07-26 | Release of the OpenAPI Specification 3.0.0 |
| 3.0.0-rc2 | 2017-06-16 | rc2 of the 3.0 specification |
| 3.0.0-rc1 | 2017-04-27 | rc1 of the 3.0 specification |
| 3.0.0-rc0 | 2017-02-28 | Implementer’s Draft of the 3.0 specification |
| 2.0 | 2015-12-31 | Donation of Swagger 2.0 to the OpenAPI Initiative |
| 2.0 | 2014-09-08 | Release of Swagger 2.0 |
| 1.2 | 2014-03-14 | Initial release of the formal document. |
| 1.1 | 2012-08-22 | Release of Swagger 1.1 |
| 1.0 | 2011-08-10 | First release of the Swagger Specification |
当前业内主要使用的文档主要包括 2.0 ， 3.0， 3.1，所以接下来也主要说明一下三者的区别，让大家也有一个认识：
{
openapi: '', // 版本描述 3.0, 3.1
swagger: '', // 版本描述 2.0
info: '', // 描述信息 三者均有
jsonSchemaDialect： "", // Schema 对象中 `$schema` 的关键字的默认值 3.0, 3.1
host: '', // host name 2.0
basePath: '', // api文档的基础path 2.0
schemes: '', // api的协议，只能是 `"http"`, `"https"`, `"ws"`, `"wss"` 2.0
servers: '', // 服务对象，也是和2.0明显区别的一点 3.0, 3.1
consumes: '', // API可以使用的MIME类型列表 2.0
produces: '', // API可以生成的MIME类型列表 2.0
paths: '', // path和api的详情信息 2.0
webhooks: "", 3.0, 3.1
components: "", 保存文档的各种schema 3.0, 3.1
definitions: '', // 保存操作生成和使用的数据类型 2.0
parametes: '', // 用于保存可在操作中使用的参数的对象 2.0
reponses: '', // 用于保存可在操作中使用的响应的对象 2.0
securityDefinitions: '', // 可以在整个规范中使用的schema definition。 2.0
security: '', // 安全相关的配置 三者均有
tags: '', // tag的列表 三者均有
externalDocs: '' // 外部文档 三者均有
}
从上面的代码可以看到，主要的区别有两点：
- 关于server相关的定义，2.0 是散布在外层，不够灵活，在3.0之后采用对象数组的形式，支持多个服务的定义
- 是path中关于schema的定义，数据格式略有调整
今天就到这里，下次给予规范实现一个 2.0 和3.0 transform
参考文档：
