团队API文档管理模型

需要解决的问题

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

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

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

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

    • GitHub项目主页

      github_wiki

    • GitHub Wiki主页

      github_wiki

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

    1. 找到GitLab中的WikiPage(如果第一次打开是空的,需要初始化才能正常连接使用,可以使用命令行说明或者直接创建第一个home页面进行初始化)

      gitlab_wiki

      gitlab_wikihome

    2. 通过Git方式直接连接到Wiki仓库并Clone到本地进行管理(注意:GitLab中的Wiki和GitHub一样,Wiki仓库和代码仓库是独立的)

      gitlab_gitaccess

    3. 打开GitBookEditor,通过Open或者Import将clone好的工程直接引用进来进行编辑和管理。 (PS:open操作是直接打开仓库文件编辑,import命令则会默认把仓库拷贝到GitBook的工作库目录Library下进行操作,如果你的Wiki仓库已经初始化并clone好推荐直接使用Open方式)

      gitbook_openimport

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

      gitbook_reposet_menu gitbook_reposet

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

      gitbook_success

      gitbook_update

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

    1. GitBook的Windows客户端连接到本地的远程仓库会报错,目前仍然无法解决,可能是私有SSL证书有关。(但是并不影响使用GitBookEditor编辑然后使用SourceTree来提交和Push)

      gitbook_sync_error

    2. 细心的筒子们会发现,GitBookEditor远程同步的时候提交操作是非常频繁的(如下图),但是我们仅仅作为文档管理使用,程序猿们不必太过纠结,只需要维护好文档内容并且只关注master分支即可。

      gitbook_commit_history

    3. 由于GitBook仍然有一些共同文件需要维护,比如SUMMARY.md,所以多人操作提交仍需要注意和避免冲突的发生。但是正如代码也无法避免冲突一样,仍然建议使用人工解决冲突和大家协定规则的方式(比如SUMMARY只由某一个人维护)进行解决。


写在最后

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

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

  • 欢迎热爱分享,追求敏捷高效的技术爱好者加入我们的社群: TBC极客技术讨论群(群号:499131721)红点直播频道:TBC极客技术分享汇(频道号:145055)

参考文章

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