开发中我们正面临的问题...

1. API发展的当下与趋势
   • 标准化API越来越多
   • 跨平台调用需求越来越普及
   • 开放平台普及化
2. API定义和修改占用了越来越多的沟通成本
3. 一个好的API管理方式意味着更高的团队开发效率

---

本次分享的关键词

• Markdown&John Gruber
• GitBook
• GitBook Editor
• GitLab

---

给研发团队的建议

• 利用API管理降低软件开发的基础沟通成本
• 通过实践找到适合自己的API管理方式

---

最好准备并安装以下软件和插件

1. SourceTree （代码管理工具）

下载地址

2. GitBookEditor （GitBook集成编辑器）

下载地址

• 使用 GitBookEditor 需要注册帐号（请提前完成响应的帐号注册）

3. GitBook（插件集成工具 命令行方式）

安装使用说明

• 注意：安装该插件需要提前安装Node.js并通过npm命令安装，大家可以登录到官网下载安装Node.js，官方网址：https://nodejs.org/

GitBook Install@2x.png

什么是Markdown

定义

• Markdown是一种可以使用普通文本编辑器编写的标记语言，通过简单的标记语法，它可以使普通文本内容具有一定的格式。

历史

• 创始人为约翰·格鲁伯（John Gruber）（2004）on Daring Fireball
• John Gruber (born 1973) is a writer, blog publisher, UI designer, and the inventor of the Markdown publishing format.

用途

• Markdown的语法简洁明了、学习容易，而且功能比纯文本更强，因此有很多人用它写博客。世界上最流行的博客平台WordPress和大型CMS如Joomla、Drupal都能很好的支持Markdown。完全采用Markdown编辑器的博客平台有Ghost和Typecho。（包含中国的简书等都官方支持）

• 淘宝的官方UED团队于2012年7月 开始使用Markdown

• 软件开发领域，用于编写说明文档，并且以“README.MD”的文件名保存在软件的目录下面。

• markdown 并不是为了取代 Html，因为根本取代不了。Markdown 的理念是，能让文档更容易读、写和随意改。HTML 是一种发布的格式，Markdown 是一种书写的格式。

• 最后一点，markdown 可以被编译为 html，比如使用在线的 Pandoc。

语法

• 标题

  
  markdown_header.png

• 列表

  
  markdown_list.png

• 换行

  
  markdown_newline.png

• 链接

  
  markdown_link.png

• 图片

  
  markdown_image.png

• 代码

  
  markdown_code.png

• 表格

  
  markdown_table.png

• 水平分割线

  
  markdown_horizontal.png

预览

• 原始代码

markdown_preview_src.png

• 成品预览

markdown_preview.png

注意事项和问题

• Markdown的格式在各个标准和网站上稍有不同，比如#标题的使用还有表格--的区分等等。建议能够找到更通用的方式解决，起码要兼容自己使用的工具显示。

基于GitBook的API文档管理

关于GitBook

• GitBook是一种电子书的编写和发布解决方案，于2014年中由两个联合创始人Samy Pessé和Aaron O'Mullan创立。
• 主要产品：
  1. https://www.gitbook.com 官网网站，提供会员注册登录和在线电子书管理和发布功能。
  2. https://www.gitbook.com/editor 电子书编辑器，支持Mac、Windows和Linux操作系统，方便的可视化IDE，用于创建、编辑和管理GitBook电子书，并且支持仓库同步。
  3. https://github.com/GitbookIO/gitbook 基于node.js的命令行工具，功能和Editor基本一致，但是支持GitBook的本地导出，也是对于开发者最方便的使用途径。（网站和开源社区搜索最多的关键词也是它）

使用步骤

1. 登录GitBook官网，注册帐号。

2. 下载并安装GitBook Editor工具，使用注册帐号登录。

   
   gitbook_editor_main.png

3. 创建在线或离线电子书，然后编辑并同步到GitBook仓库或指定的远程仓库。

   
   gitbook_editor_edit.png

4. 同步成功后可以在网站上找到编写好的电子书，可以进行在线预览或者导出成PDF等格式。如果离线的电子书也可以直接使用命令行工具进行导出等操作。

   • 网页操作

     
     gitbook_website.png

   • 在线预览

     
     gitbook_webview.png

   • PDF导出

     
     gitbook_pdfview.png

   • 本地导出HTML

   1.切换到GitBook工作目录，并且通过build命令打包HTML

   
   gitbook_build.png

   2.生成成功可以看到成功输出的_book目录

   
   gitbook_build_dir.png

   3.打开index.html就可以离线方式预览HTML版本的GitBook了

   
   gitbook_build_preview.png

注意事项和问题

• GitBook的帐号默认为个人，创建的电子书也都是个人拥有和管理。如果需要多人管理则需要创建组织并授权多人管理GitBook。（组织帐号如果想要发布Private的Book需要升级到付费帐号，最低为7美元每个月, 具体如下）

  • 多人授权

    
    gitbook_org_member@2x.png

  • 产品定价

    
    gitbook_price.png

• 离线导出eBook格式（PDF、ePub，Mobi）需要安装ebook-convert插件才可以调用命令。相关资料如下：

  • 插件下载地址（文件较大，78MB）
  • 插件官方说明文档
  • Mac下配置使用说明

总结

• GitBook本身是基于Markdown的文件组织形式，电子书的目录结构都存储在SUMMARY.md文件里。简而言之，GitBook格式就是一个Git仓库包含两个必须的文件（README.md and SUMMARY.md.）

• 因为结构简单轻便，又采用了简洁的Markdown语言，所以具有非常灵活和可API化的特性。结合Git等协作工具使用更具优势。

团队API文档管理模型

需要解决的问题

• 如何解决GitBook的团队拥有和非公开（Private）
• 结合团队现有开发流程、工具，找到有效可行方案

解决方案之：GitBook和GitLab结合使用

• 选择理由：由于我们当前的开发团队已经开始使用GitLab和SourceTree作为默认代码管理工具进行代码管理，所以结合GitLab来管理API的方式是首选

• 参照模板：参照GitHub开源库和API文档说明结合的方式，我们选定了GitLab中的Wiki

  • GitHub项目主页
  github_wiki.png
  • GitHub Wiki主页
  github_wikihome.png

• 结合GitLab中的Wiki进行API管理

  1. 找到GitLab中的WikiPage（如果第一次打开是空的，需要初始化才能正常连接使用，可以使用命令行说明或者直接创建第一个home页面进行初始化）
  gitlab_wiki.png gitlab_wikihome.png
  2. 通过Git方式直接连接到Wiki仓库并Clone到本地进行管理（注意：GitLab中的Wiki和GitHub一样，Wiki仓库和代码仓库是独立的）
  gitlab_gitaccess.png
  3. 打开GitBookEditor，通过Open或者Import将clone好的工程直接引用进来进行编辑和管理。
     （PS：open操作是直接打开仓库文件编辑，import命令则会默认把仓库拷贝到GitBook的工作库目录Library下进行操作，如果你的Wiki仓库已经初始化并clone好推荐直接使用Open方式）
  gitbook_openimport.png

  通过检查RepositorySettings验证是否和远程Git仓库连接配置正确

  gitbook_reposet_menu.png
  gitbook_reposet.png
  4. 进行正常编辑保存操作，并使用sync命令直接同步到远程仓库，如果没有问题，那么恭喜你，大功告成了。
  gitbook_success.png
  gitbook_update.png

• 可能遇到的问题和注意事项

  1. GitBook的Windows客户端连接到本地的远程仓库会报错，目前仍然无法解决，可能是私有SSL证书有关。（但是并不影响使用GitBookEditor编辑然后使用SourceTree来提交和Push）
  gitbook_sync_error.png
  2. 细心的筒子们会发现，GitBookEditor远程同步的时候提交操作是非常频繁的（如下图），但是我们仅仅作为文档管理使用，程序猿们不必太过纠结，只需要维护好文档内容并且只关注master分支即可。
  gitbook_commit_history.png
  3. 由于GitBook仍然有一些共同文件需要维护，比如SUMMARY.md，所以多人操作提交仍需要注意和避免冲突的发生。但是正如代码也无法避免冲突一样，仍然建议使用人工解决冲突和大家协定规则的方式（比如SUMMARY只由某一个人维护）进行解决。

---

写在最后

• 本文旨在为开发团队提供一种高效的API管理指南和可落地的解决方案，同时也可以作为轻文档的标准解决方案。希望对你的团队有所帮助！

• 特别鸣谢：Markdown，GitHub，GitBook，GitLab的创始人和贡献者，感谢开源和分享的精神

参考文章

1. markdown
2. Markdown-Wiki
3. John Gruber's original spec
4. GitHub Flavored Markdown