摘要：本文写的是什么平时总要写文档。所以，我所希望的事，就是在完成代码后，可以费很少的力气，就生成一个像上文中所说的可调试文档。我们接下来要做两件事生成文档文档是可调试的文档。一句话流程点击生成按钮，生成类的文档。
本文写的是什么？
平时总要写文档。不写，代码无法维护，所以不得不写。但是写文档费时费力，更可怕的是写完了读起来还很费劲，束之高阁，总感觉时间浪费掉了，真是苦不堪言。
一直以来深受“写文档”的折磨，偶然看到一篇神文，接着在网上又查了自动化工具和DSL的理论，这才茅塞顿开！虽然大部分都没看懂，但要想做到轻松写出好文档，足矣！
现在就来说说我是怎么办到的吧！
要做什么？
我们的最终目的，是写出好文档。所以，首先我们要确定：什么是好文档。
好文档就如下图所示：
上面的文档好在哪？
首先，它是文档，让你知道它的功能，参数，一目了然；
其次，它是程序，你输入参数就能马上看到结果。
所以，我所希望的事，就是在完成代码后，可以费很少的力气，就生成一个像上文中所说的可调试文档。
我们接下来要做两件事：
1、生成文档；
2、文档是可调试的文档。
怎么做？
现在要开始做了，总感觉有些无从下手，那就先从最具体的事情——目前唯一能看得见的可调试API开始分析吧。
我们最终要做出的可调试API是什么样的呢？
参考之前的效果图，简化一些来说，就是下面这个样子：
纯文字显示类名，方法，功能解释，输入参数；
有一个执行按钮；
有一个区域显示执行结果。
在这个界面中，有哪些是变量呢？
类名 列表项目 方法名 功能说明 参数数量 参数名 执行结果
其中：一个API对应着一个类名，一个方法名，一个功能说明，多个参数名，执行结果是执行后生成的。
模型分析
根据以上结果，我就可以将这个API抽象出一个模型类了:
一个API包含属性：类名，类文件所在路径，方法名，功能说明以及该方法所需要输入的参数。
而一个参数又包含属性：参数名及参数说明。
事件流
接下来分析一下整个事务流程。
一句话流程：
点击“生成”按钮，生成类的HTML文档。
这就是我们要做的事情，但是说得很不清楚。我们要生成某个类的某个方法对应的HTML文档，但是一句话没有说清。
现在我们要解释清楚，于是把它拓展开来，变成一段话：
配置文件中已指定好待生成文档的类及其方法了，点击“生成按钮”， 读取该配置文件，再依次生成文档。
我们接下去就这样继续拓展下去，直到把所有步骤都搞清楚。
最终设计
整个系统一共有三类页面：
类清单页：将类及其方法列出来，点击后跳转至API页面。
API页：列出方法说明，可以输入参数并执行该方法，可查看其执行结果。
三类页面中，第二类类清单页没有什么功能，只涉及到页面跳转，所以只用html实现就行了。
至于功能页和API页都采用MVC模式进行设计。
功能页
MVC结构
Model:API；
View:make_api_template.php；
Controller:create_api.php
MVC调用流程
用户在View层点击“生成”按钮后，触发Controller；
Controller中指定了需要生成API的类，并调用这些类中的静态方法make_api生成了Model;
Controller利用这些Model生成文档
API页
MVC结构
Model：js代码，目前还未形成独立的model；
View:生成的html页；
Controller:index.php
MVC调用流程
用户在View层输入某方法的参数，点击“执行”按钮后触发Controller；
Controller根据View页传来的参数，执行方法，得到结果后返回给View；
View接收到结果并将其显示出来
结语
我实现的版本是CohenBible。
类似的工具有很多，prmd，swagger editor， apidocjs，都很好用。
写这篇文章不是鼓励大家重复造轮子，但是自己实现过一遍，会有不一样的收获。
我为什么会想到重复造轮子呢？
其实最大的原因就是：真的不太会用上面的几个工具，只好自己实现，把整个生成文档的流程走了一遍。结果，回过头再来看上面的工具，竟然拿来就能用了！如果是按官方的教程走，不知道还要花多少时间，哈哈:)
文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。
转载请注明本文地址：https://www.ucloud.cn/yun/22784.html
摘要：本文写的是什么平时总要写文档。所以，我所希望的事，就是在完成代码后，可以费很少的力气，就生成一个像上文中所说的可调试文档。我们接下来要做两件事生成文档文档是可调试的文档。一句话流程点击生成按钮，生成类的文档。 本文写的是什么？ 平时总要写文档。不写，代码无法维护，所以不得不写。但是写文档费时费力，更可怕的是写完了读起来还很费劲，束之高阁，总感觉时间浪费掉了，真是苦不堪言。 一直以来深受...
摘要：配置配置使用概率抽样。采样率定义了对跟踪跨度进行采样的概率，其值可以介于和含之间。例如，以下配置对象将采样率更改为即每个跨度都被采样，并使用协议将跟踪发送到位于的服务器文件路径注将采样率更改为会完全禁用跟踪。目录手把手教你学Dapr - 1. .Net开发者的大时代手把手教你学Dapr - 2. 必须知道的概念手把手教你学Dapr - 3. 使用Dapr运行第一个.Net程序手把手教你学Da...
摘要：适用于，演示这是开发的一个简单的可视化库，它允许你创建所有常用的图表类型条形图，树形图，折线图，面积图等。可以轻松地对折线图和条形图进行混合和匹配以组合不同的数据集，这是非常棒的功能。 翻译：疯狂的技术宅原文：https://www.monterail.com/blo... 本文首发微信公众号：jingchengyideng欢迎关注，每天都给你推送新鲜的前端技术文章 你的程序有多...
摘要：上一篇文章手把手教你如何用构建技术文章聚合平台一介绍了如何使用搭建的运行环境，并且将与集成，对掘金进行技术文章的抓取，最后可以查看抓取结果。本篇文章将继续讲解如何利用编写一个精简的聚合平台，将抓取好的文章内容展示出来。 上一篇文章《手把手教你如何用Crawlab构建技术文章聚合平台(一)》介绍了如何使用搭建Crawlab的运行环境，并且将Puppeteer与Crawlab集成，对掘金、...
阅读 3547·2021-11-23 09:51
阅读 2778·2021-11-23 09:51
阅读 638·2021-10-11 10:59
阅读 1647·2021-09-08 10:43
阅读 3203·2021-09-08 09:36
阅读 3269·2021-09-03 10:30
阅读 3269·2021-08-21 14:08
阅读 2172·2021-08-05 09:59
