update diagnostic api docs

Author: RIT3shSapata

docs/api/paths/diagnostic/keyspace-sync.yaml

@@ -7,16 +7,39 @@
 # the file licenses/APL2.txt.
 parameters:
   - $ref: ../../components/parameters.yaml#/keyspace
-get:
+post:
   summary: Run a doc body through the sync function and return sync data.
   description: |-
-    Run a document body through the sync function and return document sync data.
+    Runs a document body through the sync function and returns document sync
+    data. If no custom sync function is provided in the request body, the
+    default or user-defined sync function for the collection is used.
+    | Document | DocID | Behaviour                                                                                                                                                                            |
+    | -------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+    | Yes      | No    | The document passed will be considered as newDoc and oldDoc will be empty                                                                                                            |
+    | Yes      | Yes   | The document passed in the body will be newDoc and DocID will be read from the bucket/collection and will be passed as the oldDoc. If DocID doesn't exist, then oldDoc will be empty |
+    | No       | No    | Will throw an error                                                                                                                                                                  |
+    | No       | Yes   | The docID will be passed in as the newDoc and oldDoc will be empty. If the document is not found, an error will be returned                                                          |
+
     * Sync Gateway Application Read Only
   requestBody:
     content:
       application/json:
         schema:
-          $ref: ../../components/schemas.yaml#/Document
+          type: object
+          properties:
+            sync_function:
+              description: |-
+                A JavaScript function that defines custom access, channel, and
+                validation logic for documents. This function will be evaluated
+                by the Sync Gateway to determine document routing, access
+                grants, and validation outcomes during synchronization.
+              type: string
+              example: |-
+                function (doc, oldDoc) {
+                  channel(doc.channels);
+                }
+            doc:
+              $ref: ../../components/schemas.yaml#/Document
   responses:
     '200':
       description: Document Processed by sync function successfully

rest/diagnostic_doc_api.go

@@ -87,7 +87,7 @@ func (h *handler) handleSyncFnDryRun() error {
 	// Only require a valid JSON payload if docid is not provided.
 	// If docid is provided, the sync function will use the document from the bucket, and the payload is optional.
 	if err != nil && docid == "" {
-		return base.HTTPErrorf(http.StatusUnprocessableEntity, "Error reading sync function payload: %v", err)
+		return base.HTTPErrorf(http.StatusBadRequest, "Error reading sync function payload: %v", err)
 	}
 
 	oldDoc := &db.Document{ID: docid}

rest/diagnostic_doc_api_test.go

@@ -1171,7 +1171,7 @@ func TestSyncFuncDryRun(t *testing.T) {
 			existingDocID:   "doc",
 			existingDocBody: `{"user":{"num":123, "name":["user1"]}, "channel":"channel1"}`,
 			expectedOutput:  SyncFnDryRun{},
-			expectedStatus:  http.StatusUnprocessableEntity,
+			expectedStatus:  http.StatusBadRequest,
 		},
 		{
 			name:            "test_case_12",