作为后端开发者,如何更优雅、便捷的生成接口文档()

对于一个后端人员,给可爱的前端妹子或者帅气的app开发小哥哥生成接口文档是一件必不可少而又十分头疼的事情。通常情况下,我们会用postman调试接口,然后用rap、甚至word等工具再编写接口文档,重复工作,十分难受。
apipost的出现,解决了所有后端开发人员的痛点。
apipost的定位是:一款提升开发、测试团队效率,可直接生成文档的API调试、管理工具。
它的便捷之处,便在于它不仅完美支持类似postman的接口调试功能,而且更重要的是,它支持快速、优雅的生成漂亮的文档。
以下界面,就是apipost接口调试控制台的全貌。
作为后端开发者,如何更优雅、便捷的生成接口文档()
文章图片
是不是很熟悉?事实上,除了类似postman那些您熟悉的配方和味道的接口调试功能,它也加入了更多适合中国人习惯的小功能。比如:
亮点小功能之:快速导入参数
apipost支持多种格式的参数导入,见下图,你再也不用一个一个参数的慢慢写了:
作为后端开发者,如何更优雅、便捷的生成接口文档()
文章图片
导入格式支持key-value和json格式:
作为后端开发者,如何更优雅、便捷的生成接口文档()
文章图片
1-1:key-value格式导入示例:
key-value格式常见的就是浏览器(F12)控制台的数据格式,见下图:
作为后端开发者,如何更优雅、便捷的生成接口文档()
文章图片
我们,复制以上请求头参数,然后粘贴到apipost,点击导入
作为后端开发者,如何更优雅、便捷的生成接口文档()
文章图片
参数则瞬间导入到了请求参数中,见下图:
作为后端开发者,如何更优雅、便捷的生成接口文档()
文章图片
以上示例只是展示了如何快速导入到header参数,其他参数比如query、body操作方式是一模一样滴。
1-2:json格式导入示例:
apipost也支持json格式的参数导入,参数格式可以如下:
{"id":123,"title":"我是标题"}
作为后端开发者,如何更优雅、便捷的生成接口文档()
文章图片
如图,点击导入,参数也快速导入到了请求参数中。
作为后端开发者,如何更优雅、便捷的生成接口文档()
文章图片
亮点小功能之:参数注释自动识别
上面我们写了如何快速导入参数,其实对于生成接口文档来说,参数描述(注释)才是最要命的,对于我们一直忙碌的程序员,花大量时间用在写文档上实在太累!
好在apipost帮我们节省了很多时间,一个参数,只要写过一次注释,下次遇到同样的参数直接选中就行。举例:
作为后端开发者,如何更优雅、便捷的生成接口文档()
文章图片
在上图中,我们针对id和title写了对应的注释:
id:“我是文章Id”
【作为后端开发者,如何更优雅、便捷的生成接口文档()】title:“我是文章标题”
当我们新建一个接口的时候,假如这个接口同样用到了id或者title等参数,点击参数描述就会呈现出刚刚输入过的参数描述,直接选中即可,不用再麻烦的打字输入了。
作为后端开发者,如何更优雅、便捷的生成接口文档()
文章图片
这个小功能是不是节约了开发小伙伴很多时间呢?
亮点小功能之:快速定位当前接口目录
左侧的目录默认都是闭合的,有时候我们不知道当前正在编辑的接口属于哪个目录,找起来相当头疼。apipost提供了“定位到当前接口目录” 功能(见下图),可以快速打开当前正在编辑的接口、文档所在的目录,是不是解决了您的大问题了呢?
作为后端开发者,如何更优雅、便捷的生成接口文档()
文章图片
其实,apipost还有很多很多更加符合中国人操作习惯的小功能,等待您去发现。
说了这么多,好像还没说到重点,apipost怎么生成接口文档呢?很简单:新版ApiPost支持分享单个项目、也支持分享单个目录或者文档:
作为后端开发者,如何更优雅、便捷的生成接口文档()
文章图片
支持设置文档链接的有效期:
作为后端开发者,如何更优雅、便捷的生成接口文档()
文章图片
支持设置文档的查看权限:
作为后端开发者,如何更优雅、便捷的生成接口文档()
文章图片
小TIPS:apipost 导出文档响应为空?
很多小伙伴问,为什么apipost 导出文档响应为空?那是因为你么有添加响应示例。
ApiPost生成的文档怎么添加响应示例?很简单:
作为后端开发者,如何更优雅、便捷的生成接口文档()
文章图片
官网:https://docs.apipost.cn/

    推荐阅读