技术选型流程及注意事项

时间：2018/8/9 9:45:55

以API文档工具选型为例

准备工作

1. 整理需求。整理出要满足的要求和额外的要求。

2. 必须

   • 使用简单
   • 快速编写接口文档。
   • 生成可视化的文档。
   • Mock服务
   • 非必需
   • 接口测试

3. 选择技术，根据需求在网上搜索满足需求的工具，列出可选项。

   • 可用工具
     • Swagger
     • API Blueprint
     • RAML
     • YApi

4. 考察工具。

   • 前期考察：
     • 开源协议。
     • 目前是否有人在维护项目。
     • 项目问题数：StackOverflow。
     • 是否是商业化项目，是否有商业公司基于此项目构建完善的生态体系，如果有的化，使用商业项目会比自己搭建生态划算。
     • 易用性，是否容易上手。

   Swagger: API语法规范，提供在线平台 * 非开源项目。 * 可以读取注释，生成接口文档。

   API Blueprint: 以API文档（简单语法）为核心，驱动Mock、测试等。API 语法规范。

   • 最后更新于2017年5月。
   • 问题数量不多。
   • 基于 Restful 风格。
   • 提供API编写规范，Mock、测试、文档渲染和根据文档生成客户端代码等功能通过第三方插件实。第三方插件可用性依赖于第三方，因此工具的可用性，需要依赖多个项目，风险较大。
   • 入门有一定的门槛，熟悉之后编写API比较方便，从接口定义、Mock接口、接口开发、接口测试 全部可以通过插件进行。

   RAML: API 语法规范。 * 截至目前更新不是很频繁，Git项目问题数量 199。 * StackOverflow 问题数为15个，且是2014年提出。 * 基于 yaml 风格的语法规范，简单但是，约束性比较弱。 * 基于插件的生态，插件和项目目前活跃度都不高。 * 基于Restful 规范。 * 存在第三方提供的，完整的文档编写、mock和测试平台。

   YApi： 可视化接口管理项目。 * 开源项目，截至文档书写日期仍在更新，问题响应速度较快。 * 国内开源项目，中文文档。 * 可视化接口文档管理工具，包含Mock、测试、权限管理等功能，适合企业管理接口。 * 简单易用，通过图形化界面管理的方式创建和编辑接口信息，不需要特定格式要求。 * 支持内网部署，数据存储依赖 mongodb 数据库。

   RAP2： 可视化接口管理项目 * 淘宝开源项目，目前比较活跃。 * 中文文档。 * 可视化接口管理，Mock接口功能（可指定数据生成规则），测试和插件功能不是很完善。 * 提供在线平台，也可本地部署。 * 简单易用。 * 界面风格不够美观，不够友好。

5. 风险

   • 停止维护

6. 其它影响因素

   • 自己以前用过。历史印象往往会影响判断。