作者 | Damon 爱数AnyShare引擎研发部-开发经理
目录
- OAS 3.0
- OAS 3.0与RESTful API
- 使用OAS 3.0
- 整体流程
- 使用案例
- 编辑器
- 文本编辑器
- GUI编辑器
- JSON Schema
- 文档展示
- SDK
- Mock
- 概述
- 使用方法
- 上传 API 文档
- Mock 地址配置
- 参考资料
OAS 3.0
API specifications可以使用YAML或JSON编写。该格式对人类和机器来说都是容易学习和读取的。完整的OpenAPI Specification参考GitHub:OpenAPI 3.0 Specification
OAS 3.0与RESTful API
使用OAS 3.0
整体流程
使用案例![](https://i-blog.csdnimg.cn/blog_migrate/4d3e9c13f0690ad87c46a386e2aeeec0.png)
说明:
- 编辑阶段:开发者进行编辑,可以选择本地或在线编辑器
- 编辑完成:将 swaggerJSON上传到 git,保证代码和 API 版本一致
- 查看阶段:从 Git上 pull API 代码,在 PC上使用 vscode查看或者在 redoc上查看,YAPI也可提供查看功能
- 测试阶段:从 Git上 pull API代码,同步到 YAPI环境
- 发布阶段:Jenkins每日构建过程中,都是用 API文件构建生成 HTML文档
编辑器
文本编辑器
vscode插件:
- OpenAPI (Swagger) Editor
- openapi-lint
- ReDoc Viewer
由于YAPI 只支持 JSON 格式的文件导入,所以推荐使用 JSON 格式存储
插件配合使用效果
注意:ReDoc Viewer插件可能有bug,第一个窗口port为9093,替换ip后即可访问,开第二个vscode窗口后,使用了错误的port,除替换ip,还要替换port为9094,再新开窗口则port依次递增。
GUI编辑器
APICURIO
安装指南:https://github.com/Apicurio/apicurio-studio/tree/master/distro/docker-compose
JSON Schema
无论是接口的返回值还是传入参数,都会大量使用到 json 对象,在 API 编辑的过程中,JSON Schema 编写是比较困难的,解决方法:
- 使用文本编辑器时,可以使用在线的 JSON Schema 生成器:https://jsonschema.net,并进行必要的删减
- 使用 APICURIO,可以使用自带的 JSON Schema 生成功能,并做必要的修改
文档展示
统一使用redoc-cli
安装:
mkdir /nodejs && cd /nodejs
npm i redoc-cli
启动服务端:
- -p:指定服务端口号
- --watch:监测指定文件/文件夹的变更(若不指定表示检测所在文件夹),刷新页面可获取最新内容
- --ssr:服务器端渲染(可选)
node /nodejs/node_modules/redoc-cli/index.js serve -p 7777 --watch=./xx.json --ssr --options.requiredPropsFirst --options.jsonSampleExpandLevel=all --options.disableSearch --options.pathInMiddlePanel --options.menuToggle --options.theme.colors.primary.main=#E60F19 --title='xxx' -t /root/api/template.hbs ./xx.json
生成HTML文件:
node /nodejs/node_modules/redoc-cli/index.js bundle --options.requiredPropsFirst --options.jsonSampleExpandLevel=all --options.disableSearch --options.pathInMiddlePanel --options.menuToggle --options.theme.colors.primary.main=#E60F19 --title='xxx' -t /root/api/template.hbs ./xx.json -o ./xx.html
命令中使用的模板:
/root/api/template.hbs
<!DOCTYPE html>
<html>
<head>
<meta charset="utf8" />
<title>{{title}}</title>
<!-- needed for adaptive design -->
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
body {
padding: 0;
margin: 0;
}
</style>
{{{redocHead}}}
<link href="https://fonts.googleapis.com/css?family=Noto+Sans+SC:300,400,700&display=swap&subset=chinese-simplified" rel="stylesheet">
</head>
<body>
{{{redocHTML}}}
</body>
</html>
AnyShare OpenDoc API:
SDK
上图为部分开源和付费的SDK生成工具,供参考
Mock
Mock 是 RESTful API 测试的一种手段,公司提供了 YAPI 进行 Mock 的使用,YAPI 也可作为文档查看平台,但是由于自身的限制,我们不采用 YAPI 进行 API 的编辑和API的管理工作。
概述
登陆方式:域账号
管理方式:
- 每个部门创建自己空间
- 每个研发项目创建自己的项目
如下图所示:
使用方法
上传 API 文档
注意:只支持 swagger json 格式的设计文档
Mock 地址配置
API 文件导入后,会自动出现 Mock 地址
配置环境,域名一般为 api.eisoo.com/mock/xx/, xx为上个页面中分配的 ID
配置完成后即可使用 Mock 功能
再次强调,YAPI 可用于 Mock 和接口查看(不支持http状态码),但是不能用管理 API,API 文件的管理一定要在 gitlab 中
参考资料
https://swagger.io/specification/
https://www.breakyizhan.com/swagger/2976.html
https://www.breakyizhan.com/swagger/2974.html