feat(spec): support recursive path creation and colon-syntax URLs

Document the MS Graph colon-syntax URL forms

    POST /v1beta1/drives/{drive-id}/root:/{path}:/children
    POST /v1beta1/drives/{drive-id}/items/{item-id}:/{path}:/children

on both create-item operations. OpenAPI cannot express the colon-delimited
path segment, so the URL forms aren't represented as separate operations,
but the description makes clear the server accepts them.

Add a @libre.graph.missingParentsBehavior query parameter (enum fail|create,
default fail) controlling recursive creation of missing intermediate
folders along a colon-syntax path. Libregraph extension; ignored for
non-colon URLs.

Author: dschmidt

api/openapi-spec/v1.0.yaml

@@ -479,6 +479,12 @@ paths:
         The request body must specify exactly one of `folder` (set to `{}` to create a folder), `file` (to create a file item), or `remoteItem` (to mount a shared item; see [sharedWithMe](#/me.drive/ListSharedWithMe) for obtaining the source `remoteItem.id`). Requests with none of these, or with more than one, return 400. Mounting a share changes the `@client.synchronize` property of the `driveItem` in [sharedWithMe](#/me.drive/ListSharedWithMe) to true.
 
         The `@libre.graph.conflictBehavior` query parameter controls what happens if a child with the same name already exists.
+
+        This endpoint also accepts the MS Graph colon-syntax URL form:
+
+            POST /v1beta1/drives/{drive-id}/root:/{path}:/children
+
+        OpenAPI cannot express the colon-delimited path segment, so this URL form is not represented as a separate operation in this specification. The server still accepts it, resolves `:/{path}:` as the parent of the new item, and applies `@libre.graph.missingParentsBehavior` to decide whether to create missing intermediate folders.
       parameters:
         - name: drive-id
           in: path
@@ -498,6 +504,16 @@ paths:
               - fail
               - replace
             default: fail
+        - name: '@libre.graph.missingParentsBehavior'
+          in: query
+          description: |
+            Controls what happens when a colon-syntax URL refers to a path whose intermediate folders don't all exist yet. `fail` (default) returns 404; `create` creates the missing intermediate folders before creating the final item. Only meaningful for colon-syntax URLs; ignored otherwise.
+          schema:
+            type: string
+            enum:
+              - fail
+              - create
+            default: fail
       requestBody:
         description: In the request body, provide a JSON object describing the new driveItem. Must specify exactly one of `folder`, `file`, or `remoteItem`. For mount-share, see [sharedWithMe](#/me.drive/ListSharedWithMe) for obtaining the source `remoteItem.id` and `permission` id.
         content:
@@ -1349,6 +1365,12 @@ paths:
         Identical request and response shape to the [drive-root variant](#/drives.root/CreateDriveItem), just with an explicit parent item id rather than the drive root.
 
         The request body must specify exactly one of `folder` (set to `{}` to create a folder) or `file` (to create a file item). Requests with none of these, or with both, return 400. The `@libre.graph.conflictBehavior` query parameter controls what happens if a child with the same name already exists.
+
+        This endpoint also accepts the MS Graph colon-syntax URL form:
+
+            POST /v1beta1/drives/{drive-id}/items/{item-id}:/{path}:/children
+
+        OpenAPI cannot express the colon-delimited path segment, so this URL form is not represented as a separate operation in this specification. The server still accepts it, resolves `:/{path}:` as the parent of the new item (relative to `item-id`), and applies `@libre.graph.missingParentsBehavior` to decide whether to create missing intermediate folders.
       parameters:
         - name: drive-id
           in: path
@@ -1376,6 +1398,16 @@ paths:
               - fail
               - replace
             default: fail
+        - name: '@libre.graph.missingParentsBehavior'
+          in: query
+          description: |
+            Controls what happens when a colon-syntax URL refers to a path whose intermediate folders don't all exist yet. `fail` (default) returns 404; `create` creates the missing intermediate folders before creating the final item. Only meaningful for colon-syntax URLs; ignored otherwise.
+          schema:
+            type: string
+            enum:
+              - fail
+              - create
+            default: fail
       requestBody:
         description: In the request body, provide a JSON object describing the new driveItem. Must specify exactly one of `folder` or `file`.
         required: true