HttpAPI规范及生态组件
从 OpenAPI / RAML / API Blueprint 到 Swagger 生态的 API 管理实践
背景
随着业务的增多，越来越多的服务需要提供 HTTP 协议的 API 接口供第三方调用。由于 HTTP API 并不像 tRPC 等协议那样有一套通用的协议规范来约束接口，API 开发者通常需要提供一份独立的 API 文档来说明每个接口的详细参数。
例如 腾讯云 API 文档 等，这些文档往往散落在各处，缺乏统一管理，而且每篇文档的撰写风格也不一致，无形中增加了 API 调用方的接入成本。
总结一下，现有的 API 管理体系普遍存在如下缺点:
- 标准不统一，管理混乱;
- 接口频繁变更，文档更新不及时;
- 开发者接入体验不友好;
- 人工编写文档耗时长。
业界规范
为了解决上述问题，业界制定了一些规范标准。这些规范定义了一个与语言无关的标准接口，允许人和计算机在不访问源代码、文档或开发者工具的前提下，就能发现并理解服务的功能。
最有名的包括 OpenAPI、RAML 和 API Blueprint。
OpenAPI 规范
OpenAPI 的前身是 Swagger，其官网也提供最新的 OpenAPI 规范定义:
备注：截至本文写作时，OpenAPI Specification 的最新正式版本已迭代到 3.1.x / 3.2.0,3.0.0 是较早但仍在大量项目中使用的稳定版本，链接保留以供参考。
RAML 规范
API Blueprint 规范
REST API 设计规范参考
生态工具
有了 API 定义规范，就可以基于它衍生出一系列工具，包括代码生成、API 文档生成与展示、API 测试、API 模拟（Mock）等。
开源工具
| API 规范 | API 文档化 | API 代码生成 | API 测试 | API 可视化编辑 | 其它 |
|---|---|---|---|---|---|
| OpenAPI | swagger-ui、openapi-generator、apicurio-studio、redoc、elements | swagger-codegen、openapi-generator、scalar | swagger-ui | swagger-editor、apicurio-studio | swagger-faker、go-swagger、从 go 源码生成 SPEC |
| RAML | raml2html | playground | webapi-parser | ||
| API Blueprint | dredd | drakov |
开源产品
YApi
YApi 是高效、易用、功能强大的 API 管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。它可以帮助开发者轻松创建、发布、维护 API，还提供了良好的交互体验：开发人员只需借助平台提供的接口数据写入工具以及简单的点击操作，即可完成接口管理。
RAP
商业化产品
1. [国内] APIFox
功能较为强大，提供了 API 设计、开发、测试一体化协作平台。
APIhub 中收录了各大互联网公司常见产品的 API 文档，例如 企业微信 API。
2. [国外] RapidAPI
号称世界上最大的 API 中心。
3. [国外] Stoplight
Stoplight 是一款全面的 API 开发平台，覆盖 API 设计、文档化、测试和发布等环节。它提供了直观、易用的界面，支持多种 API 设计语言和规范，例如 OpenAPI、Swagger 和 RAML 等。
基于 Swagger 的 API 管理方案设计
Swagger 生态组件
Swagger 是 OpenAPI 的前身，生态组件非常丰富。
例如「唐僧叨叨」的 API 文档就是基于 Swagger 实现的:
整体架构
Swagger 常用命令备忘
API 可视化（以 Swagger UI 容器方式运行）
# 容器内监听 8080,这里映射到宿主机 80 端口
docker run --rm -p 80:8080 swaggerapi/swagger-ui可视化编辑 API SPEC 文件
# swagger-editor 容器内默认监听 8080
docker run --rm -p 80:8080 swaggerapi/swagger-editor由 OpenAPI/Swagger 文件生成 Markdown 文档
npm i -g openapi-to-md
# 基本用法:openapi-to-md <source> [destination]
# -s / --sort 表示对 paths 和引用按字母序排序,不是 source 的简写
openapi-to-md openapi.json api.md