OpenAPI3 Framworks Compare
本文会横向对比几种支持OpenAPI文档生成的工具/框架。
OpenAPI 规范（OAS）定义了一个标准的、语言无关的 RESTful API 接口规范，它可以同时允许开发人员和操作系统查看并理解某个服务的功能，而无需访问源代码，文档或网络流量检查（既方便人类学习和阅读，也方便机器阅读）。正确定义 OAS 后，开发者可以使用最少的实现逻辑来理解远程服务并与之交互。
此外，文档生成工具可以使用 OpenAPI 规范来生成 API 文档，代码生成工具可以生成各种编程语言下的服务端和客户端代码，测试代码和其他用例。OpenAPI官方提供了各种语言的服务端和客户端的代码生成工具，比较著名的如OpenAPI Generator，当然也有很多优秀的第三方开发者开发的工具。
相关参考
- OpenAPI3 Specification官方文档(v3.0.3) Published 20 February 2020
- OpenAPI3 Specification官方文档(v3.1.0) Published 15 February 2021
- Awesome OpenAPI3
1. 背景描述
使用如上几种框架分别实现Swagger官方用例petstore中的一部分，然后分析这些框架的实现方式，和背后生成OpenAPI的逻辑
2. 参赛选手介绍
| 语言 | 框架 | Web功能完备 | OpenAPI版本 | Github Stars | 当前版本 | first release datae |
|---|---|---|---|---|---|---|
| Go | goa | 是 | 3 |  |
 |
2016-08-03 |
| Go | swag | 否 | 2 |  |
 |
2017-11-30 |
| Go | grpc-gateway | 是 | 2 |  |
 |
2016-07-11 |
| Go | fizz | 是 | 3 |  |
 |
2019-11-06 |
| Python | Django REST framework | 是 | 3 |  |
 |
2011-02-22 |
| Python | FastAPI | 是 | 3 |  |
 |
2018-12-16 |
| Rust | Poem | 是 | 3 |  |
 |
2021-10-14 |
3. 实现过程介绍
1. Goa
## 1. 安装goa提供的代码生成工具
go install goa.design/goa/v3/cmd/goa@v3
## 2. 创建一个design文件夹，用于描述API
mkdir -p goa_example/design
## 3. 使用goa提供的dsl描述API
## 4. 生成代码模板
goa gen goa_example/design
# 该步骤会生成gen文件夹中的所有文件，包括design文件中定义的所有接口信息、Model描述、验证方式、Protobuf描述(如果有)等所有相关信息的Go描述
## 5. (optional) 生成实现的一个example
goa example goa_example/design
# 该步骤会生成cmd文件夹，包括http server和 grpc server的启动
# 和项目根目录/{service_name}.go的文件，其中包含了各方法的默认实现(fmt.Println())
# 接下来只需要修改各方法中的具体实现为真实业务逻辑即可
- 优点
4. FAQ
1. Swagger和OpenAPI的关系和区别？
简单来说
- OpenAPI: Specification(规范)
- Swagger: Tools for implementing the specification(实现规范的一系列工具)
Swagger最初是在2010年设计RESTful API的简单开源规范。还开发了包括Swagger UI、Swagger Editor和Swagger Codegen等开源工具，以更好地实现和可视化规范中定义的 API。由规范和开源工具组成的Swagger项目变得非常流行，创建了一个庞大的社区驱动工具生态系统。
在2015年，Swagger项目被SmartBear Software收购。Swagger规范被捐赠给Linux基金会并更名为OpenAPI Specification(OAS)，是描述REST API的标准规范。
此后，Swagger已成为最受欢迎的工具套件，可在整个 API 生命周期中充分利用 OAS 的强大功能。 SmartBear Software 支持的 Swagger 工具是最流行的实现 OpenAPI 规范的工具之一，并将继续保持 Swagger 名称（Swagger Editor、Swagger UI、SwaggerHub 等）
2. JSON Schema?
JSON Schema 是一种定义JSON格式的规范，相关生态已经比较完备，各种语言的校验工具基本都有实现。
例如vscode中配置文件的代码补全和校验就是基于json schema完成的。
OpenAPI中对Json对象的描述就是使用Json schema来描述的
目前为止已经发布了多个版本的草案，其中
OAS3.0.3 采用的是Draft 00
OAS3.1.0 采用的是Draft 2020-12