# 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](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md)

## 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](https://github.com/mulesoft/oas-raml-converter/blob/master/docs/RAML10-to-OAS20.md)）

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