详解接口文档的编写，接口文档编写工具推荐
下面是关于接口文档编写-接口文档编写工具
正规的团队合作或者是项目对接，接口文档是非常重要的，一般接口文档都是通过开发人员写的。一个工整的文档显得是非重要。下面我总结下自己看到的优秀接口文档。
一、背景介绍
接口：API
API（Application Programming Interface）即应用程序接口。可以认为 API 是一个软件组件或是一个 Web 服务与外界进行的交互的接口。 目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。 从另一个角度来说，API是一套协议，规定了我们与外界的沟通方式：如何发送请求和接收响应。
我对API的理解 API就是把某些功能封装好，方便其他人调用。调用的人只要满足接口暴露给调用者的一些访问规则就能很方便使用这些功能，并且可以不需要知道这些功能的具体实现过程。
什么是接口文档？ 在实际项目开发中，web项目是前后端分离开发的，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。
二、知识剖析
接口分为四部分:
1、方法:新增(post) 修改(put) 删除(delete) 获取(get)
2、uri：以/a开头，如果需要登录才能调用的接口(如新增、修改；前台的用户个人信息，资金信息等)后面需要加/u， 即：/a/u；中间一般放表名或者能表达这个接口的单词；get方法，如果是后台通过搜索查询列表，那么以/search结尾， 如果是前台的查询列表，以/list结尾。
3、请求参数和返回参数，都分为5列：字段、说明、类型、备注、是否必填 字段是类的属性；说明是中文释义；类型是属性类型，只有String、Number、Object、Array四种类型；备注是一些解释，或者可以写一下例子， 比如负责json结构的情况，最好写上例子，好让前端能更好理解；是否必填是字段的是否必填。
4、返回参数结构有几种情况：1、如果只返回接口调用成功还是失败（如新增、删除、修改等），则只有一个结构体： code和message两个参数；2、如果要返回某些参数，则有两个结构体：1是code/mesage/data，2是data里写返回的参数,data是object类型；
三、接口文档生成工具
国产接口测试和接口文档生成工具apipost，既可以在你开发完接口之后对接口进行测试
还能够前后端实现接口联调，接口开发完善之后还可以生成各种格式的接口文档 分享接口，可以通过分享的接口链接，查看在线的接口文档
还可以下载其他格式的接口文档
如word格式的接口文档
写接口文档的工具，我尝试过很多，我之前用过txt写、用过小幺鸡、用过apizza、用过Showdoc、看云、Gitbook、ReadTheDoc、Yapi、MinDoc、eoLinker、RAR，真的是尝试过很多个，但是他们都有一些不如意的地方。
小幺鸡：样式太丑，直接是十几年前那种table的样式，每添加一行参数都要鼠标点击一下新建，编写体验很差，预览页面真的很丑，接口调试没成功过，也用过它的markdown、富文本，体验都好差
apizza：刚开始我以为终于找到一个靠谱的了，但是！响应参数文档在哪填写！！！？另外没有 markdown，没有不限层级目录结构、子参数，最后只能抛弃。
showdoc：这个是存粹写 markdown 的，虽然可以保存模板，但是用来写 api 文档真的还是太麻烦了，跟写 txt 一样，这种体验，作为懒惰的程序猿是无法忍受的。
易文档：这个是我最喜欢的，有专门的接口编写编辑器，输入很方便快捷，下面给大家介绍下。
易文档 https://easydoc.xyz，专业编写API文档工具，支持HTTP文档，markdown文档，富文本文档
支持在线接口测试，一键生成mock配置，前端不用等服务端开发完接口就能进行测试了。
看下他的预览效果，示例项目
市面很多http接口文档的编写都是直接写 Markdown 文档，这种编写起来特别麻烦。易文档在http文档方面有做专门的处理，做了很多优化体验，比如按tab就可以自动下一个输入框，可以保存一些常用的参数，方便快速引用进来，还有不限层次的子参数，参数行顺序调整。
特别强大的是，他的http文档可以自定义参数块和描述块，比如失败和成功返回的参数不一样，我们可以添加两个参数块，分别对应成功响应参数、失败响应参数
如果你想给每个返回都提供一个示例或者说明，也都没问题，可以自己添加描述块。而且块的顺序是可以调整的，非常方便。
以上就是小编为大家整理的接口文档编写-接口文档编写工具
版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。
发表评论
评论列表
好文，了解到了接口文档如何编写的方法。