82 lines
6.4 KiB
Markdown
82 lines
6.4 KiB
Markdown
|
# OpenAPI3 Framworks Compare
|
|||
|
|
|
|||
|
|
本文会横向对比几种支持OpenAPI文档生成的工具/框架。
|
|||
|
|
|
|||
|
|
OpenAPI 规范（OAS）定义了一个标准的、语言无关的 RESTful API 接口规范，它可以同时允许开发人员和操作系统查看并理解某个服务的功能，而无需访问源代码，文档或网络流量检查（既方便人类学习和阅读，也方便机器阅读）。正确定义 OAS 后，开发者可以使用最少的实现逻辑来理解远程服务并与之交互。
|
|||
|
|
|
|||
|
|
此外，文档生成工具可以使用 OpenAPI 规范来生成 API 文档，代码生成工具可以生成各种编程语言下的服务端和客户端代码，测试代码和其他用例。OpenAPI官方提供了各种语言的服务端和客户端的代码生成工具，比较著名的如[OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator)，当然也有很多优秀的第三方开发者开发的工具。
|
|||
|
|
|
|||
|
|
> 相关参考
|
|||
|
|
>
|
|||
|
|
> - [OpenAPI3 Specification官方文档(v3.0.3)](https://spec.openapis.org/oas/v3.0.3) Published 20 February 2020
|
|||
|
|
> - [OpenAPI3 Specification官方文档(v3.1.0)](https://spec.openapis.org/oas/v3.1.0) Published 15 February 2021
|
|||
|
|
> - [Awesome OpenAPI3](https://apis.guru/awesome-openapi3)
|
|||
|
|
|
|||
|
|
## 1. 背景描述
|
|||
|
|
|
|||
|
|
使用如上几种框架分别实现Swagger官方用例[petstore](https://petstore.swagger.io)中的一部分，然后分析这些框架的实现方式，和背后生成OpenAPI的逻辑
|
|||
|
|
|
|||
|
|
## 2. 参赛选手介绍
|
|||
|
|
|
|||
|
|
| 语言 | 框架 | Web功能完备 | OpenAPI版本 | Github Stars | 当前版本 | first release datae |
|
|||
|
|
|--------|--------------------------------------------------------------------------|-------------|-------------|--------------------------------------------------------------------------------|------------------------------------------------------------------------------------|---------------------|
|
|||
|
|
| Go | [goa](https://github.com/goadesign/goa) | 是 | 3 |  |  | 2016-08-03 |
|
|||
|
|
| Go | [swag](https://github.com/swaggo/swag) | 否 | 2 |  |  | 2017-11-30 |
|
|||
|
|
| Go | [grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway) | 是 | 2 |  |  | 2016-07-11 |
|
|||
|
|
| Go | [fizz](https://github.com/wI2L/fizz) | 是 | 3 |  |  | 2019-11-06 |
|
|||
|
|
| Python | [Django REST framework](https://github.com/encode/django-rest-framework) | 是 | 3 |  |  | 2011-02-22 |
|
|||
|
|
| Python | [FastAPI](https://github.com/tiangolo/fastapi) | 是 | 3 |  |  | 2018-12-16 |
|
|||
|
|
| Rust | [Poem](https://github.com/poem-web/poem) | 是 | 3 |  |  | 2021-10-14 |
|
|||
|
|
|
|||
|
|
## 3. 实现过程介绍
|
|||
|
|
|
|||
|
|
### 1. Goa
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
## 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())
|
|||
|
|
# 接下来只需要修改各方法中的具体实现为真实业务逻辑即可
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
1. 优点
|
|||
|
|
|
|||
|
|
## 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
|