终于不用再苦逼地写文档了!教你如何生成可调试的API文档
内容导读
互联网集市收集整理的这篇技术教程文章主要介绍了终于不用再苦逼地写文档了!教你如何生成可调试的API文档,小编现在分享给大家,供广大互联网技能从业者学习和参考。文章包含2960字,纯文字阅读大概需要5分钟。
内容图文
![终于不用再苦逼地写文档了!教你如何生成可调试的API文档](/upload/InfoBanner/zyjiaocheng/166/039aa00f9e3a40f8b3a7a9f65910b36b.jpg)
本文写的是什么?
平时总要写文档。不写,代码无法维护,所以不得不写。但是写文档费时费力,更可怕的是写完了读起来还很费劲,束之高阁,总感觉时间浪费掉了,真是苦不堪言。 一直以来深受“写文档”的折磨,偶然看到一篇神文,接着在网上又查了自动化工具和DSL的理论,这才茅塞顿开!虽然大部分都没看懂,但要想做到轻松写出好文档,足矣! 现在就来说说我是怎么办到的吧! 要做什么?我们的最终目的,是写出好文档。所以,首先我们要确定:什么是好文档。 好文档就如下图所示: 上面的文档好在哪? 所以,我所希望的事,就是在完成代码后,可以费很少的力气,就生成一个像上文中所说的可调试文档。 我们接下来要做两件事: 现在要开始做了,总感觉有些无从下手,那就先从最具体的事情——目前唯一能看得见的可调试API开始分析吧。 我们最终要做出的可调试API是什么样的呢? 参考之前的效果图,简化一些来说,就是下面这个样子: 纯文字显示类名,方法,功能解释,输入参数; 在这个界面中,有哪些是变量呢? 类名 列表项目 方法名 功能说明 参数数量 参数名 执行结果 其中:一个API对应着一个类名,一个方法名,一个功能说明,多个参数名,执行结果是执行后生成的。 模型分析根据以上结果,我就可以将这个API抽象出一个模型类了: 一个API包含属性:类名,类文件所在路径,方法名,功能说明以及该方法所需要输入的参数。 而一个参数又包含属性:参数名及参数说明。 事件流接下来分析一下整个事务流程。 一句话流程: 现在我们要解释清楚,于是把它拓展开来,变成一段话: 整个系统一共有三类页面: 类清单页:将类及其方法列出来,点击后跳转至API页面。 API页:列出方法说明,可以输入参数并执行该方法,可查看其执行结果。 三类页面中,第二类类清单页没有什么功能,只涉及到页面跳转,所以只用html实现就行了。 MVC结构 MVC调用流程 MVC结构 MVC调用流程 我实现的版本是CohenBible。 类似的工具有很多,prmd,swagger editor, apidocjs,都很好用。 我为什么会想到重复造轮子呢? |
内容总结
以上是互联网集市为您收集整理的终于不用再苦逼地写文档了!教你如何生成可调试的API文档全部内容,希望文章能够帮你解决终于不用再苦逼地写文档了!教你如何生成可调试的API文档所遇到的程序开发问题。 如果觉得互联网集市技术教程内容还不错,欢迎将互联网集市网站推荐给程序员好友。
内容备注
版权声明:本文内容由互联网用户自发贡献,该文观点与技术仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容, 请发送邮件至 gblab@vip.qq.com 举报,一经查实,本站将立刻删除。
内容手机端
扫描二维码推送至手机访问。