5分钟打造好用好看API文档

LiamH · · 1468 次点击 · 开始浏览    置顶

# 5分钟打造好用好看API文档 > 🤔️ 你是否遇到过这样的场景? - 对接第三方开放平台文档的时候,左手刷着接口文档看API,右手操作着接口调试工具 🧱 - 写完接口想交付或提供API文档给第三方使用,又觉得文档展示体验一般?很鸡肋? ### 前言 > 早期第三方开放平台的开放接口文档,主要以信息展示为主,基本信息包括请求方式、参数说明、返回结果等等。这里以企业微信开发者中心文档为例 👇 ![以信息展示为主接口文档 - 企业微信](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/96e8f0cd653f4b92835cdf326f516282~tplv-k3u1fbpfcp-zoom-1.image) 而在很长一段时间,为了调试开放接口,我们是不是也是经常习惯左边对着接口文档,右边打开Postman调试。 而在上周微信开放平台上线了**调试工具**,将**文档与在线调试**一体化融合。从某种意义上打破了原有单一的**信息展示**为主的局面 ![微信开放平台调试工具](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ce7196ee3fc94eaca3689c41ffcc3871~tplv-k3u1fbpfcp-zoom-1.image) 而这样带来的好处就是通过接口文档即可一键抵达调试工具台 >>> 🤔️ 那如果其他的开放平台都**支持在线调试**,是不是效率就提升了一个level? 通过上文我们看到微信实际上提供了一个调试工具赋能原有的接口文档 但是其他平台,如果想省时省力也开发一套`具备在线调试的接口文档体系` 那**Apifox**会是你最满意的选择 官网地址:[apifox.cn](https://www.apifox.cn/?utm_source=liam) > Apifox在接口文档中集成了**调试功能**、**代码在线生成**等等 👇 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ee63c82c6d634896a7d7502fda367ee9~tplv-k3u1fbpfcp-zoom-1.image) 上图是接口管理Saas服务商**Apifox**推出的**Apihub**(开放 API 共享平台)其中企业微信的开放文档。 通过文档在线调试,进一步提升开发者对接开放平台API的效率。 该平台目前已经聚合了`大部分主流第三方开放API` ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/9c0f2879c43e4b5db69579016cdc0daf~tplv-k3u1fbpfcp-zoom-1.image) 换句话说通过**Apifox赋能**的`开放API文档`都是具备在线调试、代码生成 。包括一下特征 >> **支持在线调试**:点击请求,实时显示调试结果,返回信息一目了然 > >> **自动生成代码片段**:支持自动生成代码片段,省时省力更高效 > 🤔️ 那作为个人开放者,是否可以通过Apifox发布这样好看好用的API文档? 可以的,5分钟教你搞定! ### Apifox发布API文档 首先我们在Apifox软件的在线分享Tab中找到`新建分享`按钮 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/e3ba0f7cad4e45e887382b125d8846d6~tplv-k3u1fbpfcp-zoom-1.image) 然后在新建分享的弹窗中选择分享属性(文档语言、访问密码、环境选择、分享范围等等)这里以宠物商店Demo为例 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/9bc18ef6d9bc44b5be818611e87e526b~tplv-k3u1fbpfcp-zoom-1.image) 保存成功后将鼠标移动到分享列表中的刚刚创建的分享中,点击界面中出现的打开链接 👇 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/7424bf4d1b594029bf0c50df1ba70e39~tplv-k3u1fbpfcp-zoom-1.image) 打开Apifox生成接口文档呈现如下,同样也可以支持在线调试! ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/69c87ac632bc47efbb8f767d4a76e0fb~tplv-k3u1fbpfcp-zoom-1.image) > 🤔️ 那可以在生成的接口文档在进一步自定义“装饰”下不? ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/cf320043dfcd46a8ae8c5816ddec303e~tplv-k3u1fbpfcp-zoom-1.image) 可以的,Apifox 目前提供的文档自定义的区域有 - `顶部导航菜单` - `顶部导航右侧功能区` - `文档内容底部Banner区` 可以在发布文档栏目下进行定义 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/49e4addefbc2407a8b0bdfb185169e42~tplv-k3u1fbpfcp-zoom-1.image) 后续在官网文档也有提及,将会有更多开放区域供我们DIY! 不仅如此,你还可以自定义域名。目前通过Apifox发布的文档使用 xxx.apifox.cn 格式的URL,但是你可以将你的域名直接指向你发布的文档 👇 - 1.在`发布文档 > 发布设置` 面板中设置自己自定义的域名 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/96491fa7c93d47eab7923002c7beed7f~tplv-k3u1fbpfcp-zoom-1.image) - 2.添加Apifox的`CNAME`到你域名厂商的配置中心 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/25de8ac05322475aa869d76bd42995e1~tplv-k3u1fbpfcp-zoom-1.image) 最后发布通过你自定义的接口文档,也可以申请发布到上文提到的`API Hub`中 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/68ff6105bdef408ebdc8b86abae94426~tplv-k3u1fbpfcp-zoom-1.image) 完成上述操作,你将会收获一个好用好看API文档 - API文档是支持在线调试的 - 域名是你自定义的 - 文档自定义区域是你DIY的 分享给朋友倍有面子! 官方地址:[apifox.cn](https://www.apifox.cn/?utm_source=liam) ### 最后 API文档功能只是**Apifox**强大功能中冰上一角,还提供了`API调试`、`API Mock`、`API自动化测试`等功能 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/a007d82a9aa248b8b9de108a14ae6747~tplv-k3u1fbpfcp-zoom-1.image)

有疑问加站长微信联系(非本文作者)

入群交流(和以上内容无关):加入Go大咖交流群,或添加微信:liuxiaoyan-s 备注:入群;或加QQ群:692541889

1468 次点击  
加入收藏 微博
暂无回复
添加一条新回复 (您需要 登录 后才能回复 没有账号 ?)
  • 请尽量让自己的回复能够对别人有帮助
  • 支持 Markdown 格式, **粗体**、~~删除线~~、`单行代码`
  • 支持 @ 本站用户;支持表情(输入 : 提示),见 Emoji cheat sheet
  • 图片支持拖拽、截图粘贴等方式上传