前言

目前,越来越多的项目进行前后端分离,那么就有需要比较规范的来管理API文档。而apiDoc这个API文档管理器,可以根据你项目代码的注释来进行自动生成API文档。同时支持C#、Java、JavaScript、PHP、Python等语言。

下面为具体的详细步骤。

事前准备

  • node安装,前往Node.js进行下载安装,这里一直点击下一步就可以了,很简单。(我安装的是V6.9.1)版本。

安装apiDoc

输入下面的命令进行安装

sudo npm install apidoc -g

安装完成,就是这么简单。

使用apiDoc创建文档

  • 创建项目目录

    mkdir doc && cd doc

这条命了创建了一个叫doc的文件夹,创建成功后进入doc文件夹,下面如无特别说明,所有命令均在doc文件夹下执行。

  • 创建源文件目录与输出文件目录

    mkdir src && mkdir output

在doc文件夹下创建了src目录和output目录。其中src文件夹用来写API文档,output文件夹用来存放编译后的API文档。

  • 创建描述文件

在doc文件夹下新建一个名为apidoc.json的文件,此文件的作用是用来描述API文档的相关信息。作用类似于composer.json或者前端的package.json文件,并且这个描述信息可以直接写到package.json文件中,具体的使用方法可以上官网进行查询。

下面是apidoc.json文件的内容。

  • 接着在src文件夹下新建test.js文件,也可以是PHP、java等文件。文件内容如下

  • 接着在终端输入下面的命令来生成API文档。

apidoc -i src/ -o output/

上面的命令表示将所有src文件夹内的代码全部转换成API文档并且输出到output文件夹内。如果代码编写正确的话,此时在终端内会出现info: Done字样。代表我们已经成功创建了API文档。

接着在浏览器中打开output文件夹下的index.html文件就会看到已经排版好的API文档了。

至此,一个基本的API文档已经生成。接下来讲解一下apidoc的一些进阶用法。

apiDoc进阶用法

  • 继承

在src文件夹下新建classes.php文件。代码如下。

上面的代码只写出了主要部分,省略部分用省略号代替,具体代码前往gitlab上进行查看。

在上面的代码中,我们在最开始使用@apiDefine来定义了一个公用错误返回示例。在下面的两个api中可以使用@apiUse来调用这个示例。这样我们就不用为不同API的相同错误来写两遍了。

最终的效果可以到(趣编程API文档)来进行查看。

还有许多其他apiDoc的功能可以到官网去查找使用,也许你们写出来的文档会比我写的更加好呢。

发表评论

电子邮件地址不会被公开。 必填项已用*标注