chore(docs): Refactor API Reference (#1883)

docs/api/admin/paths/collections.yaml

@@ -0,0 +1,157 @@
+post:
+  operationId: PostCollections
+  summary: Create a Product Collection
+  description: Creates a Product Collection.
+  x-authenticated: true
+  requestBody:
+    content:
+      application/json:
+        schema:
+          required:
+            - title
+          properties:
+            title:
+              type: string
+              description: The title to identify the Collection by.
+            handle:
+              type: string
+              description: >-
+                An optional handle to be used in slugs, if none is provided we
+                will kebab-case the title.
+            metadata:
+              description: >-
+                An optional set of key-value pairs to hold additional
+                information.
+              type: object
+  tags:
+    - Collection
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              collection:
+                $ref: ../components/schemas/product_collection.yaml
+get:
+  operationId: GetCollections
+  summary: List Product Collections
+  description: Retrieve a list of Product Collection.
+  x-authenticated: true
+  parameters:
+    - in: query
+      name: limit
+      description: The number of collections to return.
+      schema:
+        type: integer
+        default: 10
+    - in: query
+      name: offset
+      description: The number of collections to skip before the results.
+      schema:
+        type: integer
+        default: 0
+    - in: query
+      name: title
+      description: The title of collections to return.
+      schema:
+        type: string
+    - in: query
+      name: handle
+      description: The handle of collections to return.
+      schema:
+        type: string
+    - in: query
+      name: q
+      description: a search term to search titles and handles.
+      schema:
+        type: string
+    - in: query
+      name: created_at
+      description: Date comparison for when resulting collections were created.
+      schema:
+        type: object
+        properties:
+          lt:
+            type: string
+            description: filter by dates less than this date
+            format: date
+          gt:
+            type: string
+            description: filter by dates greater than this date
+            format: date
+          lte:
+            type: string
+            description: filter by dates less than or equal to this date
+            format: date
+          gte:
+            type: string
+            description: filter by dates greater than or equal to this date
+            format: date
+    - in: query
+      name: updated_at
+      description: Date comparison for when resulting collections were updated.
+      schema:
+        type: object
+        properties:
+          lt:
+            type: string
+            description: filter by dates less than this date
+            format: date
+          gt:
+            type: string
+            description: filter by dates greater than this date
+            format: date
+          lte:
+            type: string
+            description: filter by dates less than or equal to this date
+            format: date
+          gte:
+            type: string
+            description: filter by dates greater than or equal to this date
+            format: date
+    - in: query
+      name: deleted_at
+      description: Date comparison for when resulting collections were deleted.
+      schema:
+        type: object
+        properties:
+          lt:
+            type: string
+            description: filter by dates less than this date
+            format: date
+          gt:
+            type: string
+            description: filter by dates greater than this date
+            format: date
+          lte:
+            type: string
+            description: filter by dates less than or equal to this date
+            format: date
+          gte:
+            type: string
+            description: filter by dates greater than or equal to this date
+            format: date
+  tags:
+    - Collection
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              collections:
+                type: array
+                items:
+                  $ref: ../components/schemas/product_collection.yaml
+              count:
+                type: integer
+                description: The total number of items available
+              offset:
+                type: integer
+                description: The number of items skipped before these items
+              limit:
+                type: integer
+                description: The number of items per page