API文档自动生成续：活用 GitHub Pages

本篇文章为上篇「 API 文档自动生成工具 apiDoc 」的续篇，建议阅读完上篇后再阅读本篇。

序言

上篇文章介绍了一个 API 文档自动生成的小工具「 apidoc 」，但是最终生成的是包括了html、css 样式等在内静态文件，虽然说自己在本地可以通过浏览器预览 index.html 的方式查看生成的 API 文档，但是与我们协作的前端开发者怎么办，把静态文件打个包都丢过去？No，这样太 low 了。

下面就介绍一种超级简单的方式：通过 GitHub Pages 自动部署我们的 API 文档静态文件，并生成一个公网 URL 地址，这样只要前端开发者访问这个 URL 地址就可以看到 API 文档了。

GitHub Pages

GitHub Pages 是什么？先看下面这种图：

注意红色圈住的部分，这不就是个 URL 地址吗？点进去一看，就到了另外一个图文并茂的页面，这就是 GitHub Pages 的作用（当然图中的库有可能只是一个超链接，并不是配置的 GitHub Pages ），如果你 GitHub 使用的较多的话，你就会发现绝大部分流行的库都会有这样的 URL 地址。

API 文档部署实操

1、新建一个 git 库，使用「 apidoc 」 自动生成 API 文档相关的静态文件并将其文件夹命名为 docs 并置于 git 库的根目录下 ：

apidoc -i <输入文件位置> -o ./docs

然后将以上 docs 文件全部 push 到 github 上的代码库中。

2、进入到 github 此代码库中，点击 settings，如下图所示：

往下面翻找到 GitHub Pages ：

点击 Source 下的 None，并选择 master branch /docs folder ：

点击 save 保存，你就会得到一个 URL 地址 ：

图中的地址是我测试生成的，跟你的肯定不一样。这个 URL 地址公网可以访问，前端开发人员访问此地址就可以看到你部署的 API 文档了。

最后一步，将 URL 配置到代码库 code 首页保存即可：

通过以上步骤你已经成功的通过 GitHub Pages 生成了一个公网 URL 地址，此 URL 加载的页面正是此前自动生成的 API 文档的页面，而如果 API 接口发生改变，只需要重新生成 docs 静态文件，并 push 到 github 即可，URL是保持不变的。

至此 API 文档的部署成功完成，本文的图文步骤较为详细，希望阅读完本文后能让你有所收获。