终于不用再苦逼地写文档了!一步步教你如何生成可调试的API

本文写的是什么?


平时总要写文档。不写,代码无法维护,所以不得不写。但是写文档费时费力,更可怕的是写完了读起来还很费劲,束之高阁,总感觉时间浪费掉了,真是苦不堪言

一直以来深受“写文档”的折磨,偶然看到一篇神文,接着在网上又查了自动化工具DSL的理论,这才茅塞顿开!虽然大部分都没看懂,但要想做到轻松写出好文档,足矣!

现在就来说说我是怎么办到的吧!

要做什么?


我们的最终目的,是写出好文档。所以,首先我们要确定:什么是好文档
好文档就如下图所示:

这里写图片描述

上面的文档好在哪?
首先,它是文档,让你知道它的功能,参数,一目了然;
其次,它是程序,你输入参数就能马上看到结果。

所以,我所希望的事,就是在完成代码后,可以费很少的力气,就生成一个像上文中所说的可调试文档

我们接下来要做两件事:

  1. 生成文档;
  2. 文档是可调试的文档。

怎么做?


现在要开始做了,总感觉有些无从下手,那就先从最具体的事情——目前唯一能看得见的可调试API开始分析吧。

我们最终要做出的可调试API**是什么样**的呢?
参考之前的效果图,简化一些来说,就是下面这个样子:

这里写图片描述

纯文字显示类名,方法,功能解释,输入参数;
有一个执行按钮;
有一个区域显示执行结果。

在这个界面中,有哪些是变量呢?
1. 类名
2. 方法名
3. 功能说明
4. 参数数量
5. 参数名
6. 执行结果

其中:一个API对应着一个类名,一个方法名,一个功能说明,多个参数名,执行结果是执行后生成的。

模型分析


根据以上结果,我就可以将这个API抽象出一个模型类了:

这里写图片描述

一个API包含属性:类名,类文件所在路径,方法名,功能说明以及该方法所需要输入的参数。

而一个参数又包含属性:参数名及参数说明。

事件流


接下来分析一下整个事务流程

一句话流程
点击“生成”按钮,生成类的HTML文档。
这就是我们要做的事情,但是说得很不清楚。我们要生成某个类的某个方法对应的HTML文档,但是一句话没有说清。

现在我们要解释清楚,于是把它拓展开来,变成一段话
配置文件中已指定好待生成文档的类及其方法了,点击“生成按钮”, 读取该配置文件,再依次生成文档。
我们接下去就这样继续拓展下去,直到把所有步骤都搞清楚。

最终设计


整个系统一共有三类页面:
功能页:只有一个生成API的按钮;

这里写图片描述

类清单页:将类及其方法列出来,点击后跳转至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,都很好用。
写这篇文章不是鼓励大家重复造轮子,但是自己实现过一遍,会有不一样的收获。

我为什么会想到重复造轮子呢?
其实最大的原因就是:真的不太会用上面的几个工具,只好自己实现,把整个生成文档的流程走了一遍。结果,回过头再来看上面的工具,竟然拿来就能用了!如果是按官方的教程走,不知道还要花多少时间,哈哈:)

  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值