fix: api docs by clarifying file extension requirements in API paths

docs/openapi/config-api.yaml

@@ -6,6 +6,8 @@ source:
     summary: Config
     description: Get a config for an org, repo, or source.
     parameters:
+      - $ref: "./parameters.yaml#/orgParam"
+      - $ref: "./parameters.yaml#/repoParam"
       - $ref: "./parameters.yaml#/pathParam"
     responses:
       '200':
@@ -23,6 +25,8 @@ source:
       Create a config for an org, repo, or source.
 
     parameters:
+      - $ref: "./parameters.yaml#/orgParam"
+      - $ref: "./parameters.yaml#/repoParam"
       - $ref: "./parameters.yaml#/pathParam"
     requestBody:
       content:

docs/openapi/copy-api.yaml

@@ -6,11 +6,17 @@ source:
     summary: Copy source content
     description: |
       Copy a content source within an organization.
+      
+      **Important:** The `path` parameter works as follows:
+      - For files: Include the extension in the path (e.g., `myfile.html`)
+      - For folders: Omit the extension (e.g., `myfolder`)
+      Examples:
+      - Copy file: `/copy/{org}/{repo}/myfile.html`
+      - Copy folder: `/copy/{org}/{repo}/myfolder`
     parameters:
       - $ref: "./parameters.yaml#/orgParam"
       - $ref: "./parameters.yaml#/repoParam"
       - $ref: "./parameters.yaml#/pathParam"
-      - $ref: "./parameters.yaml#/extParam"
     requestBody:
       content:
         multipart/form-data:

docs/openapi/move-api.yaml

@@ -6,11 +6,17 @@ source:
     summary: Move source content
     description: |
       Move a content source within an organization.
+      
+      **Important:** The `path` parameter works as follows:
+      - For files: Include the extension in the path (e.g., `myfile.html`)
+      - For folders: Omit the extension (e.g., `myfolder`)
+      Examples:
+      - Move file: `/move/{org}/{repo}/myfile.html`
+      - Move folder: `/move/{org}/{repo}/myfolder`
     parameters:
       - $ref: "./parameters.yaml#/orgParam"
       - $ref: "./parameters.yaml#/repoParam"
       - $ref: "./parameters.yaml#/pathParam"
-      - $ref: "./parameters.yaml#/extParam"
     requestBody:
       content:
         multipart/form-data:

docs/openapi/payloads.yaml

@@ -7,6 +7,6 @@ putSourceJson:
       lastRollout: 'Wed, 29 Nov 2023 01:20:40 GMT'
       timesAskedWhyNoNesting: 492
 copySourceForm:
-  summary:
+  summary: Copy source form data example
   value: |
     destination: '/aemsites/geometrixx/path/to/file.html'

docs/openapi/responses.yaml

@@ -21,16 +21,19 @@ source:
             - $ref: "./schemas.yaml#/aemSheet"
       image/png:
         schema:
-          type: binary
+          type: string
+          format: binary
       image/jpg:
         schema:
-          type: binary
+          type: string
+          format: binary
       application/pdf:
         schema:
-          type: binary
+          type: string
+          format: binary
       image/svg+xml:
         schema:
-          type: xml
+          type: string
 
 list:
   '200':
@@ -85,13 +88,24 @@ version-list:
             source:
               editUrl: "https://da.live/edit#/adobecom/blog/my-cool-post"
               contentUrl: "https://content.da.live/adobecom/blog/my-cool-post"
-              status: 201
               props:
                 readyForLoc: true
                 lastRollout: Wed, 29 Nov 2023 01:20:40 GMT
             aem: 
               previewUrl: "https://main--blog--adobecom.aem.page/my-cool-post"
               liveUrl: "https://main--blog--adobecom.aem.live/my-cool-post"
+'200':
+  description: Success - returns config data.
+  content:
+    application/json:
+      schema:
+        $ref: "./schemas.yaml#/aemSheet"
+'200-list':
+  description: Success - returns version list.
+  content:
+    application/json:
+      schema:
+        $ref: "./schemas.yaml#/version-list"
 '204':
   description: The request was completed successfully.
 

docs/openapi/schemas.yaml

@@ -4,7 +4,8 @@ source:
   properties:
     data:
       description: The content to store at the specified location.
-      type: blob
+      type: string
+      format: binary
 
 copy:
   source:
@@ -64,15 +65,14 @@ sourceInfo:
       allOf:
         - required:
             - editUrl
-            - viewUrl
-            - status
+            - contentUrl
         - properties:
             editUrl:
               description: The edit URL of the resource.
               type: string
               format: url
-            viewUrl:
-              description: The view URL of the resource. For a site, used in AEM fstab.yaml.
+            contentUrl:
+              description: The content URL of the resource.
               type: string
               format: url
             status:
@@ -110,8 +110,6 @@ sourceList:
             type: object
 
 version-list:
-  required:
-    - versions
   description: List of audits and sources.
   type: array
   items:

docs/openapi/source-api.yaml

@@ -4,12 +4,15 @@ source:
     tags:
       - Source
     summary: Get source content
-    description: Get a content **source** from an organization.
+    description: |
+      Get a content **source** from an organization.
+
+      **Important:** For files, the `path` parameter must include the file extension (e.g., `myfile.html`, `data.json`).
+      The full URL would be: `/source/{org}/{repo}/myfile.html`
     parameters:
       - $ref: "./parameters.yaml#/orgParam"
       - $ref: "./parameters.yaml#/repoParam"
       - $ref: "./parameters.yaml#/pathParam"
-      - $ref: "./parameters.yaml#/extReqParam"
     responses:
       '200':
         $ref: "./responses.yaml#/source/200"
@@ -28,11 +31,16 @@ source:
     summary: Create source content
     description: |
       Create a content **source** within an organization.
+
+      **Important:** For files, the `path` parameter must include the file extension (e.g., `myfile.html`, `data.json`).
+      For folders, omit the extension (e.g., `myfolder`).
+      Examples:
+      - File: `/source/{org}/{repo}/myfile.html`
+      - Folder: `/source/{org}/{repo}/myfolder`
     parameters:
       - $ref: "./parameters.yaml#/orgParam"
       - $ref: "./parameters.yaml#/repoParam"
       - $ref: "./parameters.yaml#/pathParam"
-      - $ref: "./parameters.yaml#/extReqParam"
     requestBody:
       content:
         multipart/form-data:
@@ -55,12 +63,19 @@ source:
     tags:
       - Source
     summary: Delete source content
-    description: Delete the content **source** or **directory**.
+    description: |
+      Delete the content **source** or **directory**.
+
+      **Important:** The `path` parameter works as follows:
+      - For files: Include the extension in the path (e.g., `myfile.html`)
+      - For folders: Omit the extension (e.g., `myfolder`)
+      Examples:
+      - Delete file: `/source/{org}/{repo}/myfile.html`
+      - Delete folder: `/source/{org}/{repo}/myfolder`
     parameters:
       - $ref: "./parameters.yaml#/orgParam"
       - $ref: "./parameters.yaml#/repoParam"
       - $ref: "./parameters.yaml#/pathParam"
-      - $ref: "./parameters.yaml#/extParam"
     responses:
       '204':
         $ref: "./responses.yaml#/204"

docs/openapi/version-api.yaml

@@ -4,12 +4,15 @@ get:
     tags:
       - Version
     summary: Get source version
-    description: Returns version of a given source.
+    description: |
+      Returns version of a given source.
+
+      **Important:** The `guid` parameter must include the file extension (e.g., `version-123.html`, `v2.json`).
+      Example: `/versionsource/{org}/{repo}/version-123.html`
     parameters:
       - $ref: "./parameters.yaml#/orgParam"
       - $ref: "./parameters.yaml#/repoParam"
       - $ref: "./parameters.yaml#/guidParam"
-      - $ref: "./parameters.yaml#/extReqParam"
     responses:
       '200':
         $ref: "./responses.yaml#/source/200"
@@ -24,12 +27,15 @@ post:
     tags:
       - Version
     summary: Create source version
-    description: Create a version of a given source.
+    description: |
+      Create a version of a given source.
+
+      **Important:** The `path` parameter must include the file extension (e.g., `myfile.html`, `data.json`).
+      Example: `/versionsource/{org}/{repo}/myfile.html`
     parameters:
       - $ref: "./parameters.yaml#/orgParam"
       - $ref: "./parameters.yaml#/repoParam"
       - $ref: "./parameters.yaml#/pathParam"
-      - $ref: "./parameters.yaml#/extReqParam"
     responses:
       '200':
         $ref: "./responses.yaml#/200-list"
@@ -44,12 +50,15 @@ list:
     tags:
       - Version
     summary: List source versions
-    description: Returns a list of versions for a given source.
+    description: |
+      Returns a list of versions for a given source.
+
+      **Important:** The `path` parameter must include the file extension (e.g., `myfile.html`, `data.json`).
+      Example: `/versionlist/{org}/{repo}/myfile.html`
     parameters:
       - $ref: "./parameters.yaml#/orgParam"
       - $ref: "./parameters.yaml#/repoParam"
       - $ref: "./parameters.yaml#/pathParam"
-      - $ref: "./parameters.yaml#/extReqParam"
     responses:
       '200':
         $ref: "./responses.yaml#/version-list/200"