如何搭建api接口文档(如何搭建api接口文档)

网友投稿 744 2023-02-25


本篇文章给大家谈谈如何搭建api接口文档,以及如何搭建api接口文档对应的知识点,希望对各位有所帮助,不要忘了收藏本站喔。 今天给各位分享如何搭建api接口文档的知识,其中也会对如何搭建api接口文档进行解释,如果能碰巧解决你现在面临的问题,别忘了关注本站,现在开始吧!

本文目录一览:

使用 API Blueprint 来编写 API 接口文档

API Blueprint 用来编写API文档如何搭建api接口文档的一种标记语言如何搭建api接口文档,类似于Markdown,具体的语法规则可以在 API Blueprint documentation 查看,文档里面还有一个简短的 API Blueprint tutorial 建议先仔细阅读一下这个教程。

使用 API Blueprint 文档,配合一些开源的工具可以把接口文档渲染成 html 再搭配一个静态服务器,就可以很方便的共享给同事。

相对于 word 这种富文本格式的文档来说, API Blueprint 是纯文本,这样可以很方便的使用版本控制工具 Git 来控制版本。

另外,配合一些工具,可以直接生成一个 mock data 数据,这样只要和后端的同学约定好接口格式,那么前端再开发的时候可以使用 mock data 数据来做测试,等到后端写好接口之后再做联调就可以了。

API Blueprint 社区提供了一些文本编辑器的插件,可以识别 API Blueprint 语法支持语法高亮。

使用 apiblueprint 编写好文档使用,可以使用开源社区提供的一个工具 aglio 来把接口文档渲染成 html 文件, aglio 还会启动一个静态服务器,这样就可以在浏览器里面查看渲染好的文档了。

aglio 的使用教程,可以直接查看官方开发仓库的 readme 文档。另外,这里也有一份资料 使用API-Blueprint 编写 API 文档 可以参考。

YAPI:从0搭建API文档管理工具

最近在找一款API文档管理工具,之前有用过Swagger、API Manager、Confluence,现在用如何搭建api接口文档的还是Confluence。

我个人一直不喜欢用Swagger,感觉“代码即文档”,让代码里的文档无处不在,已经对代码造成了一定的入侵了。API Manager就是一个纯API文档管理的工具了。Confluence是万能的,也是最简单的,支持各种插件在线安装,可以有各种布局,支持MD文档,也支持表格、代码块等。

最近看到一篇文章在说YAPI,就准备搭建一个试试效果如何。

YAPI是去哪儿网开源的一款API管理工具,理念如下:

特性:

选择YAPI试试手的原因是因为我看到了它支持MockServer,这样前端开发同学就不用等待后端同学了。主要是我也懒得搭建一套mock服务,有这样一款工具何乐而不为呢如何搭建api接口文档?所以今天就找了一台服务器安装了一下。考虑排版问题,就以图片形式放出来了。

nodeJS长期支持版本官网下载地址:https://nodejs.org/dist/v10.16.0/node-v10.16.0-linux-x64.tar.xz,下载后执行如下命令:
nodeJS安装完毕。
YAPI安装,GitHub上已经有比较详细的文档了,地址:https://github.com/YMFE/yapi,这里说一下两种部署方式:

可视化部署:
yapi安装完毕,访问进行可视化配置一步一步往下走即可。

命令行部署(推荐方式):
yapi安装完毕,访问:{config.json中配置的port}即可访问。

node需要安装pm2模块,使用pm2模块后台运行yapi:
运行成功页面:
至此,YAPI就安装完毕了,简单实用一下还是不错的,因为是国产的,整体操作风格还是比较习惯的。在YAPI这里接口更改还有记录哦~
后面再慢慢体验这个里面的一些高级功能吧,比如MockServer、接口测试等功能。

大家还有什么更好用的API管理工具?如何搭建api接口文档你觉得一款优秀的API管理工具应该都有哪些必须的功能?欢迎推荐和讨论!

如何优雅的“编写”api接口文档

1. 拼写要准确
接口函数一旦发布就不能改如何搭建api接口文档了,要保持兼容性,拼写错误也不能改如何搭建api接口文档了,所以要仔细检查拼写,否则会被同行嘲笑很多年。
著名悲剧:unix 如何搭建api接口文档的 creat
2. 不仅是英文单词不要拼错,时态也不要错。
比如:
返回bool的判断函数,单数要用 is 复数要用are,这样你的命名就和文档中的描述保持了一致性。
表示状态的变量或者函数要注意时态,比如 onXxxxChanged 表示xxx已经变化了,isConnecting表示正在连接。
正确的时态可以给使用者传递更丰富的信息。
3. 函数最好是动宾结构
动宾结构就是 doSomething,这样的函数命名含义明确
比如: openFile, allocBuffer, setName
如果这个函数的动词宾语就是这个对象本身,那么可以省略掉宾语
4. 属性命名最好是定语+名词
比如 fileName, maxSize, textColor
5. 不要用生僻单词,这不是秀英语的地方,也不要用汉语拼音
比如:rendezvous,估计大多数人要去查词典才知道什么意思,这个词源自法语,是约会的意思。
Symbian OS里有个用它命名的函数,开发Symbian的是英国人,也许人家觉得很平常吧,反正如何搭建api接口文档我是查了词典才知道的。
6. 不要自己发明缩写
除非是约定俗成已经被广泛使用的缩写,否则老老实实用完整拼写。
坏例子: count-cnt, manager-mngr password-pw button-btn
现代的IDE都有很好的自动完成功能,名字长一点没关系的,可读性更重要。
7. 保持方法的对称性,有些方法一旦出现就应该是成对的,
比如 有open就要有close,有alloc就要有free,有add就要有remove,这些单词基本是固定搭配的,使用者就很容易理解。
如果 open对应clear就有点让人困惑了。

自己怎么建API文档?

去看看怎么做chm电子书的教程吧,这不是一个简单的事。网上也有很多工具,只要你往这个方向前进,总能做出来的。
实际上chm只是一种已经过编译的html文件,在如果是java的api文档,在eclipse中有自动生成文档的命令,但生成的是html文件。如果你学会怎么把这些html编译成chm,那么这个api文档不就做出来了吗?

会SQL语句,就能快速开放你的数据接口API

如果你是非技术开发工程,不熟悉Java、PHP、Python、Golang这些后端的编程语言,但熟悉MySQL、Oracle、SQL Server、PostgreSQL这些数据库的查询操作,当你需要把现有的数据库的数据,通过API接口形式提供给外部人员使用时,使用派框架·接口大师这个工具,就能轻松实现。

派框架·接口大师,是一套研发、管理和开放API接口的软件源代码和解决方案,基于PhalApi开源接口框架+Vue前后端分离,可用于快速搭建各类企业级接口平台。

适合用于开发新项目、已使用PhalApi开源框架的项目,或现有项目的系统重构,可用于快速搭建:OpenAPI、接口平台、数据平台、PaaS平台、SaaS平台、BaaS平台、开放平台等。

本地安装好后,就可以开始使用了。

假设我们已经在以下的国家数据库表pp_countries:

字段 sortname:表示国家简称,name 表示国家全称,还有区号phonecode,以及经纬度字段。

现在使用 接口大师 这个工具,介绍如何低代码开发、管理和开放你的数据API接口。

进入接口大师的管理后台,进入接口管理-低代码接口开发-添加接口。

接口设计类型选择:生成数据库表接口API。

在接口服务名称这里,把类名改成你的数据库表名,不需要带表前缀,同时使用大写开头的坨峰法写法。

在接口参数填写需要支持的搜索参数。

例如,支持国家名称的模糊匹配。

接下来,点击生成代码。会生成类似如下的PHP代码:

例如,找到SQL这一行的语句:

改成你自己的SQL语句,例如模糊搜索国家名。

同时把参数调整成左右模糊匹配:

然后,点击【保存并发布】。

发布接口后,就可以在OpenAPI在线接口文档看到刚刚添加发布的新数据接口。

点击可以进入新接口的在线接口文档。截图如下:

你可以在线进行接口测试。填入需要搜索的国家名,例如:输入A。

可以看到接口返回以下数据:

开启调试模式后,还可以看到背后执行的SQL语句和执行时间:

完善接口文档

你还可以补充添加接口返回的结构、字段说明。

再次发布后,就可以在前台接口文档查看到:

最后,再来看下如何把你开发添加好的新数据接口API开放给其他人。

开发者的主要使用流程是:

所以,开发者,需要先到开放平台注册一个新账号,然后登录。

再创建新的应用并等待后台审核通过:

应用通过审核后,根据app_key和密钥,申请接口访问令牌。

获取到访问令牌access_token后,就可以调用和使用你新添加的数据API接口。 关于如何搭建api接口文档和如何搭建api接口文档的介绍到此就结束了,不知道你从中找到你需要的信息了吗 ?如果你还想了解更多这方面的信息,记得收藏关注本站。 如何搭建api接口文档的介绍就聊到这里吧,感谢你花时间阅读本站内容,更多关于如何搭建api接口文档、如何搭建api接口文档的信息别忘了在本站进行查找喔。

版权声明:本文内容由网络用户投稿,版权归原作者所有,本站不拥有其著作权,亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容,请联系我们jiasou666@gmail.com 处理,核实后本网站将在24小时内删除侵权内容。

上一篇:element 结合vue 在表单验证时有值却提示错误的解决办法
下一篇:vue 项目常用加载器及配置详解
相关文章

 发表评论

暂时没有评论,来抢沙发吧~