接口文档生成器_php 怎么调试 api,终于不用再苦逼地写文档了！教你如何生成可调试的API文档

这篇文章是关于什么的？

总是要写文档的，不写的话代码就没法维护了，所以不得不写。但是写文档费时费力，更要命的是写完之后读起来还是很费劲，总觉得浪费时间，如果放在一边就太惨了。

一直被“写文档”困扰着，偶然看到一篇很棒的文章，然后在网上查了一下自动化工具和DSL的理论，顿时豁然开朗！虽然大部分内容我都看不懂，但足以轻松写出好的文档了！

现在让我告诉你我是怎么做的！

该怎么办？

我们的最终目标是编写优秀的文档。因此，首先我们需要确定什么是优秀的文档。

一份好的文档看起来是这样的：

上述文件有何好处？

首先，它是一份文档，让你一眼就了解它的功能和参数；

其次，它是一个程序，你输入参数并立即看到结果。

所以，我希望的是，完成代码后，我可以用很少的努力来生成像上面提到的那样的可调试文档。

我们接下来要做两件事：

1.生成文档；

2.该文档可调试。

如何做？

现在我就要开始了，我总是有点不知从哪里开始。所以让我们从最具体的东西开始吧——目前唯一可见的可调试 API。

我们最终想要制作一个什么样的可调试API？

参考前面的效果图，为了简化，它看起来像这样：

纯文本显示类名、方法、函数解释、输入参数；

有一个执行按钮；

有一个区域显示执行的结果。

这个接口里有哪些变量呢？

类名

列表项

方法名称

功能说明

参数数量

参数名称

执行结果

其中：一个API对应一个类名、一个方法名、一个函数描述、多个参数名，执行后产生执行结果。

模型分析

基于以上结果，我可以将这个API抽象成一个模型类：

一个API包含以下属性：类名、类文件路径、方法名、功能描述、方法所需输入的参数。

一个参数包含属性：参数名称、参数描述。

事件流

接下来我们来分析一下整个交易的流程。

一句话流程：

单击“生成”按钮为该类生成 HTML 文档。

这就是我们想要做的，但是不太清楚，我们想为某个类的某个方法生成 HTML 文档，但是一句话说不清楚。

现在我们需要解释清楚，所以我们将其扩展为一段：

配置文件中已经指定了需要生成的文档的类和方法，点击“生成按钮”即可读取配置文件，并按顺序生成文档。

我们会继续以此方式扩展，直到所有步骤都清晰为止。

最终设计

整个系统有三种类型的页面：

功能页面：只有一个按钮，生成API；

类列表页：列出类及其方法，点击后跳转到API页面。

API页面：列出方法描述，允许您输入参数并执行方法，并查看其执行结果。

在这三类页面中，第二类列表页没有任何功能，只涉及页面跳转，因此只使用HTML就可以实现。

功能页面和API页面采用MVC模型设计。

功能页

MVC 结构

模型：API；

视图：.php；

:.php

MVC调用流程

当用户点击View层中的“生成”按钮时触发；

指定需要生成API的类，并调用这些类中的静态方法生成Model；

使用这些模型生成文档

API 页面

MVC 结构

模型：js代码，还未形成独立的模型；

查看：生成的html页面；

:索引.php

MVC调用流程

用户在View层输入某个方法的参数，点击“执行”按钮即可触发；

根据View页面发送的参数，执行方法并将结果返回给View。

View 接收结果并显示

结论

类似的工具还有很多，比如prmd、、，都非常好用。

本文并不是为了鼓励你重新发明轮子而写的，但是如果你自己去实现的话，你将获得不同的好处。

我为什么想到重新发明轮子？

其实最大的原因是我真的不知道上面的工具怎么用，所以只好自己实现，把整个文档生成流程都走一遍。结果回头再看上面的工具，居然马上就能用了！如果按照官方教程来做的话，不知道要花多少时间，哈哈：）