[Docs] Add descriptions to Snapshot Management namespace (#857)

* [Docs] Add descriptions to Snapshot Management namespace

Signed-off-by: Archer <[email protected]>

Author: Naarcha-AWS

spec/namespaces/sm.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: OpenSearch Snapshot Management API
-  description: API for automating snapshot management tasks.
+  description: The Snapshot Management API automates snapshot management tasks.
   version: 1.0.0
 
 paths:
@@ -128,120 +128,122 @@ components:
 
   responses:
     sm.get_policies@200:
-      description: Successfully retrieved the list of snapshot management policies.
+      description: The API successfully retrieved the list of snapshot management policies.
       content:
         application/json:
           schema:
             $ref: '../schemas/sm._common.yaml#/components/schemas/GetPoliciesResponse'
 
     sm.create_policy@201:
-      description: Successfully created the snapshot management policy.
+      description: The API successfully created the snapshot management policy.
       content:
         application/json:
           schema:
             $ref: '../schemas/sm._common.yaml#/components/schemas/PolicyResponse'
     sm.create_policy@400:
-      description: Bad request when creating the snapshot management policy.
+      description: The API encountered a bad request when creating the snapshot management policy.
       content:
         application/json:
           schema:
             $ref: '../schemas/sm._common.yaml#/components/schemas/BadRequestResponse'
 
     sm.get_policy@200:
-      description: Successfully retrieved the snapshot management policy.
+      description: The API successfully retrieved the snapshot management policy.
       content:
         application/json:
           schema:
             $ref: '../schemas/sm._common.yaml#/components/schemas/PolicyResponse'
     sm.get_policy@404:
-      description: Snapshot management policy not found.
+      description: The API could not find the snapshot management policy.
       content:
         application/json:
           schema:
             $ref: '../schemas/sm._common.yaml#/components/schemas/NotFoundResponse'
 
     sm.update_policy@200:
-      description: Successfully updated the snapshot management policy.
+      description: The API successfully updated the snapshot management policy.
       content:
         application/json:
           schema:
             $ref: '../schemas/sm._common.yaml#/components/schemas/PolicyResponse'
     sm.update_policy@404:
-      description: Snapshot management policy not found.
+      description: The API could not find the snapshot management policy.
       content:
         application/json:
           schema:
             $ref: '../schemas/sm._common.yaml#/components/schemas/NotFoundResponse'
 
     sm.delete_policy@200:
-      description: Successfully deleted the snapshot management policy.
+      description: The API successfully deleted the snapshot management policy.
       content:
         application/json:
           schema:
             $ref: '../schemas/sm._common.yaml#/components/schemas/DeletePolicyResponse'
     sm.delete_policy@404:
-      description: Snapshot management policy not found.
+      description: The API could not find the snapshot management policy.
       content:
         application/json:
           schema:
             $ref: '../schemas/sm._common.yaml#/components/schemas/NotFoundResponse'
 
     sm.explain_policy@200:
-      description: Successfully explained the state of the snapshot management policy.
+      description: The API successfully explained the state of the snapshot management policy.
       content:
         application/json:
           schema:
             $ref: '../schemas/sm._common.yaml#/components/schemas/PolicyExplanation'
 
     sm.start_policy@200:
-      description: Successfully started the snapshot management policy.
+      description: The API successfully started the snapshot management policy.
       content:
         application/json:
           schema:
             type: object
             properties:
               acknowledged:
                 type: boolean
+                description: Whether the API acknowledged the start operation.
 
     sm.stop_policy@200:
-      description: Successfully stopped the snapshot management policy.
+      description: The API successfully stopped the snapshot management policy.
       content:
         application/json:
           schema:
             type: object
             properties:
               acknowledged:
                 type: boolean
+                description: Whether the API acknowledged the stop operation.
 
   parameters:
     sm.create_policy::path.policy_name:
       name: policy_name
       in: path
-      description: The snapshot management policy name.
+      description: The name of the snapshot management policy to create.
       required: true
       schema:
         type: string
 
     sm.get_policy::path.policy_name:
       name: policy_name
       in: path
-      description: The snapshot management name.
+      description: The name of the snapshot management policy to retrieve.
       required: true
       schema:
         type: string
 
     sm.get_policies::query.from:
       name: from
       in: query
-      description: The index to retrieve snapshot management policies from.
+      description: The starting index from which to retrieve snapshot management policies.
       schema:
         default: 0
         type: integer
 
     sm.update_policy::path.policy_name:
       name: policy_name
       in: path
-      description: The snapshot management policy name.
+      description: The name of the snapshot management policy to update.
       required: true
       schema:
         type: string
@@ -265,31 +267,31 @@ components:
     sm.delete_policy::path.policy_name:
       name: policy_name
       in: path
-      description: The snapshot management policy name.
+      description: The name of the snapshot management policy to delete.
       required: true
       schema:
         type: string
 
     sm.explain_policy::path.policy_name:
       name: policy_name
       in: path
-      description: The snapshot management policy name.
+      description: The name of the snapshot management policy to explain.
       required: true
       schema:
         type: string
 
     sm.start_policy::path.policy_name:
       name: policy_name
       in: path
-      description: The snapshot management policy name.
+      description: The name of the snapshot management policy to start.
       required: true
       schema:
         type: string
 
     sm.stop_policy::path.policy_name:
       name: policy_name
       in: path
-      description: The snapshot management policy name.
+      description: The name of the snapshot management policy to stop.
       required: true
       schema:
         type: string
@@ -304,22 +306,22 @@ components:
     sm.get_policies::query.queryString:
       name: queryString
       in: query
-      description: Filters the returned snapshot management policies based on query string.
+      description: The query string to filter the returned snapshot management policies.
       schema:
         type: string
 
     sm.get_policies::query.sortField:
       name: sortField
       in: query
-      description: The name of the query field to sort on.
+      description: The name of the field to sort the snapshot management policies by.
       schema:
         type: string
 
     sm.get_policies::query.sortOrder:
       name: sortOrder
       in: query
-      description: The order to sort the snapshot management policy result.
+      description: The order to sort the snapshot management policies.
       schema:
         type: string
         enum: [asc, desc]
-        default: asc
+        default: asc