fix: 修复api文档

README.md

@@ -25,7 +25,7 @@
 - raml1.0暂时没有tags的服务，因此通过路径来维护接口的分组，参见`raml2swagger.js`
 - 通过displayName指定接口名字
 - 一些traits如response，在面对数组时用引号括起来如 `is: [response: { typeName: 'User[]' }]`
-- 对于一些traits如pagable，在同时包含queryParameters和responses时会有bug，导致typeName无法正确处理，这里可以考虑将pagable的traits分成两个分别处理queryParameters和responses
+- 对于一些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结构。

routes/question/question.raml

@@ -18,14 +18,14 @@ post:
     get:
       displayName: 老师获取某题目类型的所有题目
       description: type为空则获取所有
-      is: [pagable: { typeName: Question }]
+      is: [pagable, response: { typeName: PageQuestion }]
       queryParameters: 
         type: QuestionType
   /questions/assignmentType:
     get:
       displayName: 老师获取某作业类型的所有题目
       description: type为空则获取所有
-      is: [pagable: { typeName: Question }]
+      is: [pagable, response: { typeName: PageQuestion }]
       queryParameters: 
         type: AssignmentType
   /keyword:

routes/user/user.raml

@@ -33,7 +33,7 @@
     is: [response: {typeName: User }]
   get:
     displayName: 管理员搜索用户列表
-    is: [pagable: { typeName: User }]
+    is: [pagable, response: { typeName: PageUser }]
     queryParameters: 
       search:
         type: string

traits/pagable.raml

@@ -5,31 +5,4 @@ queryParameters:
     description: 页数
   limit:
     type: integer
-    description: 每页数量
-responses: 
-  200:
-    body:
-      type: object
-      properties:
-        code: integer
-        data:
-          properties: 
-            content: <<typeName>>[]
-            pagable:
-              properties:
-                pageNumber: integer
-                pageSize: integer
-                offset: integer
-                paged: boolean
-                unpaged: boolean
-            last: boolean
-            totalPages: integer
-            totalElements: integer
-            first: boolean
-            sort:
-              properties:
-                sorted: boolean
-                unsorted: boolean
-            numberOfElements: number
-            size: integer
-            number: integer
+    description: 每页数量

types/PageEntity.raml

@@ -0,0 +1,22 @@
+#%RAML 1.0 DataType
+# PageEntity
+type: object
+properties: 
+  pagable:
+    properties:
+      pageNumber: integer
+      pageSize: integer
+      offset: integer
+      paged: boolean
+      unpaged: boolean
+  last: boolean
+  totalPages: integer
+  totalElements: integer
+  first: boolean
+  sort:
+    properties:
+      sorted: boolean
+      unsorted: boolean
+  numberOfElements: number
+  size: integer
+  number: integer

types/index.raml

@@ -54,4 +54,9 @@ AssignmentType: !include ./enums/AssignmentType.raml
 AssignmentStatus: !include ./enums/AssignmentStatus.raml
 DeployEnvironment: !include ./enums/DeployEnvironment.raml
 DeployStatus: !include ./enums/DeployStatus.raml
-BuildStatus: !include ./enums/BuildStatus.raml
+BuildStatus: !include ./enums/BuildStatus.raml
+
+# Page
+PageEntity: !include ./PageEntity.raml
+PageUser: !include ./page/PageUser.raml
+PageQuestion: !include ./page/PageQuestion.raml

types/page/PageQuestion.raml

@@ -0,0 +1,5 @@
+#%RAML 1.0 DataType
+# PageUser
+type: PageEntity
+properties:
+  content: Question[]

types/page/PageUser.raml

@@ -0,0 +1,5 @@
+#%RAML 1.0 DataType
+# PageUser
+type: PageEntity
+properties:
+  content: User[]