apidoc实现API文档自动生成

欢迎关注我的个人公众号：周先生自留地

现在越来越流行前后端分离，使得前后端解耦。前后端的联系来源于数据接口，所以后端每次实现数据接口后都需要给前端写API接口文档，但是每次手写API文档很麻烦而且降低工作效率，其实有很多框架可以实现API文档自动生成，最著名的可能是swagger。但是swagger对于windows版本NodeJS开发者有点不友好，所以我尝试了一下最后放弃了，最后选择了使用apidoc来自动化生成API文档。

why?

        为什么我们要使用apidoc来自动化生成API文档？它有什么样的优势呢？

apidoc可以根据注释自动生成api文档，我们只需要把注释按照apidoc语法来写，不需要手动写markdown。

apidoc生成的文档相比markdown，漂亮直观又实用。

如果API接口修改或者更新，直接修改代码的注释中即可。

那我们接下来来看看apidoc具体是如何进行使用的。首先需要先安装NodeJS环境，我默认大家都已经安装过NodeJS环境。

安装apidoc依赖

我们先使用npm在全局安装apidoc，命令为：

npminstall  -g  apidoc

配置apidoc

配置apidoc一般有两种方式：创建apidoc.json文件或者在package.json中进行配置。我直接选择在package.json里面进行配置。

在package.json底部添加apidoc的配置，主要的几个配置参数在这里大概解释一下：

name：项目名称

version：项目版本

description：项目介绍

title：浏览器显示的标题内容

url：接口前缀，比如http://www.niyueling.cn

最基本的配置完成，下一步我们可以按照apidoc要求为接口实现注释我们可以先看看apidoc官网文档：

左边为我们一般需要使用的属性，我们可以写一个接口注释来看看：

我们来依次看看这几个参数：

@api参数定义了接口的请求方式，我的接口均为post，我们看看文档对api参数的解释：

配置文件我设置接口前缀地址为：

http://www.niyueling.cn

api参数我设置为：

@api{POST} /users/regist 用户注册

所以相当于method为post，请求接口：

http://www.niyueling.cn/users/regist

接口标题为用户注册。

@apiDescription参数不用多说，为接口描述。

@apiName参数为API接口名称，接口名称不允许重复。

@apiParam看名称就可以看出是定义参数，我们先看看文档定义：

可以看出可以对参数进行具体设置，设置长度，类型，取值范围，备注等。我们可以那上面我设置的account字段来分析，其实我account字段就是设置字段类型为string类型，备注为用户手机号必填。

@apiGroup参数其实就是给接口进行分组，比如注册登陆接口同属于用户类接口。

@apiVersion参数其实就是设置接口版本

当然apidoc不可能就这么简陋的几个参数，我在这里也不打算把所有参数尝试一遍，所以挂上apidoc文档地址，有需要可以自行查看：

http://apidocjs.com/

接下来，我们接口注释按照apidoc文档要求书写了，下一步就是按照注释自动生成API文档了。apidoc生成文档使用命令：

apidoc-i  router/  -o  doc

命令解析：使用apidoc命令，-i后面跟着我们需要打包的接口文件夹，比如我所有接口文件都放置在router文件夹下，-o后面选择我们要生成文档的文件夹，我在根路径新建文件夹doc放置。

提示Done代表生成文档成功，我们现在看下doc文件夹：

可以看到生成一堆文件，我们访问index.html看看效果：

可以看到我们按照文档书写注释的接口全部生成API文档了。客户需要文档的时候你丢一个链接过去是不是比丢一个文档过去逼格高了许多呢。当然我们在本地项目搭建的，你如果整个项目发布服务器自然可以外网访问API文档，但是本地项目的话外网无法访问，所以我选择了将doc文件夹直接放到服务器nginx的html目录下，配置nginx.conf进行访问。首先在usr/share/nginx/html下新建目录API，将doc文件夹下所有文件上传到API文件夹下：

接着配置nginx.conf配置文件，路径为：

etc/nginx/nginx.conf

在http下配置server节点，指向API/index.html。域名配置为www.niyueling.cn。配置完成，我们可以测试nginx配置是否正确，命令为：

nginx-t

配置如果没有问题，则重启nginx，命令为：

nginx-s  reload

然后我们可以访问http://www.niyueling.cn看看是否能看到我们生成的API文档：

可以看到，我们成功将API文档配置到外网进行访问。当然前提服务器需要装nginx环境。安装环境我就不多说了，可以看文章底部文章进行安装。本篇文章介绍apidoc的基本使用到这里差不多结束了，谢谢大家的观看，如果喜欢我的文章，欢迎关注我的个人公众号：周先生自留地

推荐阅读

玩转服务器---运行环境搭建

初识Node.js(一) 安装Node.js环境

谈谈Nginx的反向代理