Merge pull request #14379 from opf/chore/maintain-projects-api-spec

[chore] maintained project collection api specification

docs/api/apiv3/components/examples/project_collection.yml

@@ -0,0 +1,40 @@
+# Example: Project collection
+---
+value:
+  _type: Collection
+  count: 2
+  total: 2
+  pageSize: 20
+  offset: 1
+  _embedded:
+    elements:
+      - _hint: Project resource shortened for brevity
+        id: 1
+        identifier: initialproject
+        name: DeathStar construction
+        active: true
+        public: true
+      - _hint: Project resource shortened for brevity
+        id: 2
+        identifier: mysecret
+        name: Palpatine's secret plan
+        active: true
+        public: false
+  _links:
+    self:
+      href: '/api/v3/projects?filters=%5B%5D&offset=1&pageSize=20'
+    jumpTo:
+      href: '/api/v3/projects?filters=%5B%5D&offset=%7Boffset%7D&pageSize=20'
+      templated: true
+    changeSize:
+      href: '/api/v3/projects?filters=%5B%5D&offset=1&pageSize=%7Bsize%7D'
+      templated: true
+    representations:
+      - href: '/projects.csv?filters=%5B%5D&offset=1&pageSize=20'
+        identifier: csv
+        type: text/csv
+        title: CSV
+      - href: '/projects.xls?filters=%5B%5D&offset=1&pageSize=20'
+        identifier: xls
+        type: application/vnd.ms-excel
+        title: XLS

docs/api/apiv3/components/schemas/link.yml

@@ -26,6 +26,9 @@ properties:
   identifier:
     type: string
     description: An optional unique identifier to the link object
+  type:
+    type: string
+    description: The MIME-Type of the returned resource.
 
 example:
   href: '/api/v3/work_packages'

docs/api/apiv3/components/schemas/project_collection_model.yml

@@ -0,0 +1,38 @@
+# Schema: ProjectCollectionModel
+---
+allOf:
+  - $ref: './collection_model.yml'
+  - type: object
+    required:
+      - _links
+      - _embedded
+    properties:
+      _links:
+        type: object
+        required:
+          - self
+          - representations
+        properties:
+          self:
+            allOf:
+              - $ref: "./link.yml"
+              - description: |-
+                  This file links collection
+                  
+                  **Resource**: ProjectStorageCollectionModel
+          representations:
+            type: array
+            items:
+              allOf:
+                - $ref: "./link.yml"
+                - description: |-
+                    A project collection representation in a specific file format.
+      _embedded:
+        type: object
+        required:
+          - elements
+        properties:
+          elements:
+            type: array
+            items:
+              $ref: './project_model.yml'

docs/api/apiv3/openapi-spec.yml

@@ -497,6 +497,8 @@ components:
       $ref: './components/examples/project.yml'
     ProjectBody:
       $ref: './components/examples/project_body.yml'
+    ProjectCollection:
+      $ref: './components/examples/project_collection.yml'
     QueriesModel:
       $ref: './components/examples/queries.yml'
     QueryModel:
@@ -631,8 +633,6 @@ components:
       "$ref": "./components/schemas/list_capabilities_model.yml"
     List_of_NewsModel:
       "$ref": "./components/schemas/list_of_news_model.yml"
-    List_projectsModel:
-      "$ref": "./components/schemas/list_projects_model.yml"
     List_projects_by_versionModel:
       "$ref": "./components/schemas/list_projects_by_version_model.yml"
     MarkdownModel:
@@ -675,6 +675,8 @@ components:
       "$ref": "./components/schemas/priorities_model.yml"
     PriorityModel:
       "$ref": "./components/schemas/priority_model.yml"
+    ProjectCollectionModel:
+      "$ref": "./components/schemas/project_collection_model.yml"
     ProjectModel:
       "$ref": "./components/schemas/project_model.yml"
     ProjectStorageCollectionModel:

docs/api/apiv3/paths/memberships_available_projects.yml

@@ -14,7 +14,10 @@ get:
       content:
         application/hal+json:
           schema:
-            $ref: '../components/schemas/list_projects_model.yml'
+            $ref: '../components/schemas/project_collection_model.yml'
+          examples:
+            'simple project collection':
+              $ref: '../components/examples/project_collection.yml'
     '403':
       content:
         application/hal+json:

docs/api/apiv3/paths/projects.yml

@@ -69,7 +69,10 @@ get:
       content:
         application/hal+json:
           schema:
-            $ref: '../components/schemas/list_projects_model.yml'
+            $ref: '../components/schemas/project_collection_model.yml'
+          examples:
+            'simple project collection':
+              $ref: '../components/examples/project_collection.yml'
     '400':
       description: Returned if the client sends invalid request parameters e.g. filters
       content: