Merge branch 'master' of http://47.100.18.120:3000/API-DOC/SEEC-II

README.md

@@ -22,8 +22,10 @@
 参见[github](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md)
 
 ## raml2swagger处理
-raml1.0暂时没有tags的服务，因此通过路径来维护接口的分组，参见`raml2swagger.js`
-
+- 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结构。

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/assignment/codework/NestedOneUnitTest.raml

@@ -6,7 +6,7 @@ properties:
     type: integer
     description: 用例id，注意生产环境和测试环境的用例数目不一样，顺序无法保证，该属性并非unique的
   name:
-    type: strng
+    type: string
     description: 测试用例名称
   isPass:
     type: boolean

types/assignment/codework/NestedScore.raml

@@ -6,7 +6,7 @@ properties:
     type: integer
     description: 用例id，注意生产环境和测试环境的用例数目不一样，顺序无法保证，该属性并非unique的
   name:
-    type: strng
+    type: string
     description: 测试用例名称
   passed:
     type: boolean

types/assignment/codework/TestRecord.raml

@@ -1,6 +1,6 @@
 #%RAML 1.0 DataType
 # TestRecord
-type: TestRecord
+type: object
 properties:
   id:
     type: integer
@@ -16,5 +16,5 @@ properties:
     type: boolean
     description: 是否全部通过
   detail:
-    type: NestedOneUnitTestVO[]
+    type: NestedOneUnitTest[]
     description: 测试的用例信息

types/index.raml

@@ -33,7 +33,7 @@ NestedScore: !include ./assignment/codework/NestedScore.raml
 NestedOneUnitTest: !include ./assignment/codework/NestedOneUnitTest.raml
 CodeWorkResult: !include ./assignment/codework/CodeWorkResult.raml
 CodeWorkProject: !include ./assignment/codework/CodeWorkProject.raml
-CodeWorkProjectGeneral: !include ./assignment/codework/CodeWorkProjectGeneral.raml
+CodeProjectGeneral: !include ./assignment/codework/CodeProjectGeneral.raml
 CodeWorkDeploy: !include ./assignment/codework/CodeWorkDeploy.raml
 CodeWorkDeployRecord: !include ./assignment/codework/CodeWorkDeployRecord.raml
 BuildRecordDTO: !include ./assignment/codework/BuildRecordDTO.raml
@@ -58,4 +58,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[]