百家饭OpenAPI工具更新到了v0.6.0版本,带来了全新的API工作台和配套的客户端工具,本周我们将分篇介绍v0.6.0版本的各项更新功能,
昨天我们讲完了API的在线测试,前端同学们完成了测试,就可以写代码了,对不对?不用着急,我们还继承了JS代码自动生成功能,希望把代码编写也省了。
上一篇我们介绍了0.6.0版本中新集成进来的swag命令,通过这个命令,Golang程序可以快速生成API文档(Java通过swagger也可以,介绍点击这里),下面我们要介绍生成的API文档如何快速的进行分享和文档化。
一键同步API文档
如果你是使用Golang,swag命令会自动生成swagger.json/swagger.yaml文档,这就是以json/yaml格式存储的API详情,如果打开,内容大概如下:
如果是java并和我们一样使用knife4j的话,Swagger文档会通过网页查看,例如常见会在htttp://localhost:8080/doc.html,注意这个端口是你Java服务的端口。
百家饭v0.6.0版本支持这两种方式的swagger文档导入,只需要使用客户端中的openapi proxy命令即可。
例如java执行:
openapi proxy localhost:8080
Golang可以执行
openapi proxy .\swag\swagger.json
运行后会显示如下信息:
PS D:\workspace\baijiafan\core\bin\_> openapi proxy localhost:8080
connect to rongapi.cn
[44:05][INFO] 连接Domain服务器 server=rongapi.cn
config is D:\workspace\baijiafan\core\bin\_\certs\rongapi.cn\1_8_默认客户端证书
[44:05][INFO] 创建上传OpenAPI定义
[44:05][INFO] 开始接收请求
[44:05][INFO] 创建成功,点击可查看分享数据源 url=https://rongapi.cn/api/detail/42
[44:05][INFO] 开始接收请求
点击提示中的url,就可以快速打开上传到百家饭平台的文档啦
更多API获取方式
除了一键从后端代码生成以外,直接打开工作台,还提供了以下多种创建API文档的方式:
- 手动创建/加载本地缓存
- 编辑后的文档会在本地浏览器缓存,可以重新加载
- 导入其他软件生成的OpenAPI/Swagger文档
- 2.0版本或3.0版本均可
- 支持json/yaml两种格式
- 如果是新来的用户,可以尝试编辑公开API,借此熟悉工作台功能
API的编辑和分享
导入API或者创建API之后,左侧的侧边栏会激活,界面会自动切换到编辑页面。
编辑页面是类word结构,我们希望这个页面的编辑结果,可以直接作为API文档使用,以便开发人员或项目人员,无论在文档阶段还是在开发阶段,都可以最小化创建和维护API文档的工作量。
为了这个目标,右侧顶部的菜单提供了5个按钮
- 纯文档模式——隐藏编辑按钮,页面呈现纯文档格式,方便查看、复制和粘贴,以便开发人员在编辑项目文档时使用
- 上传/更新——将编辑结果同步到平台
- 二维码分享——获得文档的分享链接,链接可以在移动端或者PC端查看
- 文档配置——提供文档的信息配置功能
其中,分享功能可以在移动端预览,详细的协作功能需要在PC打开
而API配置功能则可以配置API的分享参数,包括是否公开可见,查看是否需要提取码等信息
如果配置了提取码,其他用户查看该文档时,需要输入对应的提取码才可以查看。
标准API编辑功能
提交的API可以进一步的进行编辑,编辑的结果会实时在文档模式中展示,例如点击基础信息旁边的编辑按钮,会直接在文档的该章节位置展示编辑面板,编辑确认后,文档信息就直接以文档的形式进行展示。


API信息编辑
除基本信息编辑之外,比较复杂的就是API信息编辑了,API信息编辑面板如下
每个API都需要指定以下的内容信息:
- URL地址,该API接口对外提供服务的调用地址
- 调用方法,调用该地址需要用哪种HTTP方法(Get/Post/Put等)
- 查询参数,调用该方法需要在HEADER、路径或query参数中附带的参数值,百家饭还支持输入计算值,详见说明文档
- 请求内容,在Body中提交的具体数据的格式
- 返回内容,返回内容的具体定义,可以定义多种返回类型的标准模板,以便调用方可以清楚知道自己是获得了哪种返回,比如是正常返回还是错误返回等
- 安全信息,访问该接口需要使用的安全模式。
使用上面的操作方式,我们就可以从代码生成API文档,并完成和其他同事的交流工作,如有必要,还可以进行进一步的编辑工作,明天,我们进一步介绍,其他同事拿到该文档之后的测试和调用工作要怎么展开。
欢迎大家试用百家饭OpenAPI平台 v0.6.0版本!