Maison >développement back-end >tutoriel php >终于不用再苦逼地写文档了!教你如何生成可调试的API文档
本文写的是什么?
平时总要写文档。不写,代码无法维护,所以不得不写。但是写文档费时费力,更可怕的是写完了读起来还很费劲,束之高阁,总感觉时间浪费掉了,真是苦不堪言。 一直以来深受“写文档”的折磨,偶然看到一篇神文,接着在网上又查了自动化工具和DSL的理论,这才茅塞顿开!虽然大部分都没看懂,但要想做到轻松写出好文档,足矣! 现在就来说说我是怎么办到的吧! 要做什么?我们的最终目的,是写出好文档。所以,首先我们要确定:什么是好文档。 好文档就如下图所示: 上面的文档好在哪? 所以,我所希望的事,就是在完成代码后,可以费很少的力气,就生成一个像上文中所说的可调试文档。 我们接下来要做两件事: 现在要开始做了,总感觉有些无从下手,那就先从最具体的事情——目前唯一能看得见的可调试API开始分析吧。 我们最终要做出的可调试API是什么样的呢? 参考之前的效果图,简化一些来说,就是下面这个样子: 纯文字显示类名,方法,功能解释,输入参数; 在这个界面中,有哪些是变量呢? 类名 列表项目 方法名 功能说明 参数数量 参数名 执行结果 其中:一个API对应着一个类名,一个方法名,一个功能说明,多个参数名,执行结果是执行后生成的。 模型分析根据以上结果,我就可以将这个API抽象出一个模型类了: 一个API包含属性:类名,类文件所在路径,方法名,功能说明以及该方法所需要输入的参数。 而一个参数又包含属性:参数名及参数说明。 事件流接下来分析一下整个事务流程。 一句话流程: 现在我们要解释清楚,于是把它拓展开来,变成一段话: 整个系统一共有三类页面: 类清单页:将类及其方法列出来,点击后跳转至API页面。 API页:列出方法说明,可以输入参数并执行该方法,可查看其执行结果。 三类页面中,第二类类清单页没有什么功能,只涉及到页面跳转,所以只用html实现就行了。 MVC结构 MVC调用流程 MVC结构 MVC调用流程 我实现的版本是CohenBible。 类似的工具有很多,prmd,swagger editor, apidocjs,都很好用。 我为什么会想到重复造轮子呢? |