写点什么

只需三步,开启 API 文档简洁之美

用户头像
CODING DevOps
关注
发布于: 2021 年 05 月 21 日
只需三步,开启 API 文档简洁之美

连接世界,不能含糊


API 最初出现时通常被用作操作系统的库,而且几乎都在本地的系统中运行。到 2000 年代初,它们已脱离本地运行环境,成为远程交互数据的重要技术。现如今,API 不仅仅是一种技术连接,也成为了一种商业连接。通过开放 API,个人或者企业可以打开自由之门,向客户、合作伙伴提供数字化产品和服务。API 网关作为管理 API 的平台,也在朝着为 API 开发者提供更丰富、完整的服务方向前进。近期,腾讯云 API 网关在现有 API 全生命周期管理能力基础上,联合 CODING API 文档产品团队,为开发者提供了 API 文档生成工具,基于这个工具开发者可以按需发布 API 文档。


腾讯云 API 网关(以下简称 API 网关)是腾讯云 Severless 团队推出的 API 托管服务,能提供 API 的完整生命周期管理,包括创建、维护、发布、运行、下线等。您可使用 API 网关封装自身业务,将您的数据、业务逻辑或功能安全可靠的开放出来,用以实现自身系统集成、以及与合作伙伴的业务连接。


精准简洁的 API 文档可以降低 API 协作的复杂度,给予 API 调用方更直观的 API 信息,解决了之前 API 信息通过口口相传导致的低效率问题,简化并加速 API 集成过程。例如在常见的前后端开发协作场景中,通过一份接口文档,就可以实现前后端并行开发:后台开发者把 API 托管在 API 网关上,配好 mock server,利用 API 文档功能把 API 信息提供给前端同学,来实现前后端分离。API 文档可以解决的问题不仅仅于此:


  • 如果你把 API 当做接口,那么你需要让使用方知道该如何对接这个系统,那么你的 API 文档就是你提供的详细说明书。


  • 如果你把 API 当作契约,那么你需要让合作方详细了解你们之间的规则,你的 API 文档就是各方之间的完整协议。


  • 如果你把 API 当作商品,那么你需要让你的客户知道可以按什么方式下单,你的 API 文档就是你提供的精美菜单。


现在,在腾讯云 API 网关控制台,只用三步就可快速发布您的 API 文档。


三步开启简洁 API 文档


步骤 1:在您登录「腾讯云 API 网关控制台」后,在工具一栏选择 「API 文档」,就可以针对你现有的 API 创建对应文档。



选择好您要发布的 API,剩下的都交给 CODING API 文档与 API 网关。



步骤 2:喝上几口热水的功夫,就可以看到自动构建完毕的 API 文档链接,你可以随时随地将这个链接和口令分享给你的协作者。



步骤 3:拿到链接与口令后,你的协作者就可以在浏览器中看到清晰、简洁、规范的 API 文档。三栏的经典文档格式,同时展示 API 列表、 API 详情与调用范例,更符合开发者阅读习惯。适当的颜色高亮与恰到好处的间距用来展示每个 API 的详细调用说明:包括 URL、Request、Response 等等信息。一旦 API 接口内容发生改变(虽然 API 不常变),只要在 API 文档工具里点击「更新」,不变的 API 文档地址,最新的 API 文档内容。



好用怎么就不能好看?


对于开发者,从一行代码,到一个函数,再到一个应用程序、一个 API 文档或者一篇技术博客,这些工作成果都是你或者你所在团队的名片,我们希望你的工作成果不仅高效还体面。CODING 开发团队深耕 API 协作方式多年,带来了令人赏心悦目的 API 文档,只为带来沉浸的阅读体验。API 文档工具现已在腾讯云 API 网关正式上线并免费开放, API 网关用户可以立即拥有全新的 API 文档。



关于 CODING


对于 API 文档功能有更加多样化需求的用户,可以选择登录 CODING 使用更加全面的 API 文档管理功能,包括支持 OpenAPI / Postman / Apidoc API 描述格式导入文档、自由选择开放文档方式等等,开始有序的 API 文档协作。不仅仅是 API 文档,致力于“让开发更简单”的 CODING,提供了从代码托管、项目协同、持续集成、制品库、持续部署、文件管理/Wiki 等的一站式研发协作工具,欢迎您登录 CODING.NET 了解更多。

用户头像

CODING DevOps

关注

还未添加个人签名 2018.04.23 加入

涵盖了软件开发从构想到交付的一切所需,助力企业实践敏捷开发与 DevOps,提升软件交付质量与速度。

评论

发布
暂无评论
只需三步,开启 API 文档简洁之美