SEEC-II

API-DOC/SEEC-II

该项目为SEEC-II的api文档仓库

维护须知

项目使用yapi + raml作为维护该文档库的流程即

• 1.开发人员更新文档，push到仓库
• 2.触发仓库的webhook，调用ci钩子
• 3.ci自动构建，通过oas-raml-converter工具将raml转化为swagger.json
• 4.ci通过yapi import，自动导入接口到yapi

其中yapi的接口管理平台地址：yapi.seecoder.cn
目前yapi的功能只做项目的管理、接口的展示与mock，如需要其他功能可基于其开源版本二次开发。

一些好处

• 通过结合ci的自动化流程，保证团队其他成员都能方便查看项目的接口，同时用raml的语言方便重用接口的数据结构。
• 开发者更新文档后，不需要通知其他团队成员git pull，yapi平台上的接口保证与仓库是一致的，其他开发者不需要繁琐地输入命令。
• 分组与项目的管理，开发者不需要来来回回在各个项目的仓库切换。
• 实时Mock，开发者无需自己维护Mock服务，yapi保证mock的服务是最新的。

raml语法

参见github

raml2swagger处理

• raml1.0暂时没有tags的服务，因此通过路径来维护接口的分组，参见raml2swagger.js
• 通过displayName指定接口名字
• 一些traits如response，在面对数组时用引号括起来如 is: [response: { typeName: 'User[]' }]
• 对于一些traits如pagable，在同时包含queryParameters和responses时会有bug，导致typeName无法正确处理，因此这里pagable只处理queryParameters，返回的实体通过定义通用PageEntity，并继承创造相应实体再使用response来解决（这里出现这个问题的根本原因是raml的语义在swagger中缺失，详情见github）

如何为其他api文档仓库接入ci？

• 该仓库定义了一些比较好的split 来帮助开发者维护raml文件，同时用了一些常用的traits机制方便重用某些结构，你可以参照该仓库的结构定义自己的raml结构。
• 依赖上需要oas-raml-converter，并在raml2swagger中处理api的路径与接口分组的关系。
• 联系ci负责人，给你的文档仓库添加ci钩子与ci的构建脚本。
• 到yapi上创建项目，获取它的token，并在新仓库中定义yapi-import.json，详情参见yapi swagger数据导入。