敏捷开发之API管理之道

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

  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插件才可以调用命令。相关资料如下:

总结

  • 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
    1. 通过Git方式直接连接到Wiki仓库并Clone到本地进行管理(注意:GitLab中的Wiki和GitHub一样,Wiki仓库和代码仓库是独立的)
    gitlab_gitaccess.png
    1. 打开GitBookEditor,通过Open或者Import将clone好的工程直接引用进来进行编辑和管理。
      (PS:open操作是直接打开仓库文件编辑,import命令则会默认把仓库拷贝到GitBook的工作库目录Library下进行操作,如果你的Wiki仓库已经初始化并clone好推荐直接使用Open方式)
    gitbook_openimport.png

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

    gitbook_reposet_menu.png

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

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

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

写在最后

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

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

参考文章

  1. markdown
  2. Markdown-Wiki
  3. John Gruber's original spec
  4. GitHub Flavored Markdown
最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 206,126评论 6 481
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 88,254评论 2 382
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 152,445评论 0 341
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 55,185评论 1 278
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 64,178评论 5 371
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 48,970评论 1 284
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 38,276评论 3 399
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 36,927评论 0 259
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 43,400评论 1 300
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,883评论 2 323
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,997评论 1 333
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 33,646评论 4 322
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 39,213评论 3 307
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 30,204评论 0 19
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,423评论 1 260
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 45,423评论 2 352
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 42,722评论 2 345

推荐阅读更多精彩内容