专栏首页Node Python Go全栈开发API文档自动生成续:活用 GitHub Pages

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 文档的部署成功完成,本文的图文步骤较为详细,希望阅读完本文后能让你有所收获。

本文分享自微信公众号 - Node Python Go全栈开发(gh_9ccbe5e0dfb3),作者:rifewang

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2017-03-22

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • Elasticsearch(四)

    对于 ES,当我们了解了 mapping 和 analysis 的相关内容之后,使用者更关心的问题往往是如何构建查询语句从而搜索到自己想要的数据。因此,本文将会...

    凌虚
  • 数据管道 Logstash 入门

    •监听某个目录下的日志文件,读取文件内容,处理数据,写入 influxdb 。•从 kafka 中消费消息,处理数据,写入 elasticsearch 。

    凌虚
  • 从 GitHub 上获取文件内容

    我依稀记得 Java 的 Spring Cloud 中有一个重要的部分就是集中配置:

    凌虚
  • GitHub 上值得关注的 5 个技术周刊

    基于 GitHub 的文件存储、代码托管、协同编辑、技术内容聚合等特性,许多开发者纷纷跑到上面开博客写文章了。

    GitHubDaily
  • 怎样使用GitHub Pages搭建个人博客

    创建一个名为 USERNAME.github.io 的仓库,其中 USERNAME 为你的 GitHub 用户名。

    DevOps持续交付
  • 码云正式支持 Pages 功能

    Pages 功能一直以来呼声都非常之高,现在终于不负各位 OSCers 众望,码云 Pages 功能闪亮登场! 码云 Pages 是一个免费的静态网页托管服务...

    码云Gitee
  • 简单编程思想

    在编写程序的时候,经常会想一下:我要做什么,我在做什么,更好的方法是把详细需求落实到文档,并时刻核对文档(有文档前提下)。

    wfaceboss
  • 一步一步教你注册GitHub账号及简单使用

    GitHub 是一个面向开源及私有软件项目的托管平台,因为只支持 git 作为唯一的版本库格式进行托管,故名 GitHub。

    JiekeXu之路
  • 人工智能语音进化史三部曲

    关于人工智能诞生没有统一说法,有部分学者以1950年“人工智能之父”马文·明斯基建造世界上第一台神经网络计算机为起点。且以当年语音交互起始到现在,大致经历三段演...

    企鹅号小编
  • 微软出品·kubernetes最新学习指南 v3.0

    Kubernetes正在席卷应用开发世界。到2022年,全球超过75%的组织将在生产环境中运行容器化应用程序。Kubernetes正在塑造应用程序开发和管理的未...

    公众号: 云原生生态圈

扫码关注云+社区

领取腾讯云代金券