[Docs] Add and edit observability descriptions (#864)

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

Author: Naarcha-AWS

spec/namespaces/observability.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
-  title: OpenSearch Observability Object API
-  description: API for retrieving and managing Observability Objects.
+  title: OpenSearch Observability API
+  description: The Observability API manages observability objects that monitor and analyze OpenSearch clusters.
   version: 1.0.0
 paths:
   /_plugins/_observability/_local/stats:
@@ -98,13 +98,13 @@ components:
             $ref: '../schemas/observability._common.yaml#/components/schemas/ObservabilityObject'
   responses:
     observability.list_objects@200:
-      description: Successful response of retrieving all Observability Objects.
+      description: The API successfully retrieved all observability objects.
       content:
         application/json:
           schema:
             $ref: '../schemas/observability._common.yaml#/components/schemas/ObservabilityObjectList'
     observability.create_object@200:
-      description: Created
+      description: The API successfully created the observability object.
       content:
         application/json:
           schema:
@@ -113,69 +113,72 @@ components:
               objectId:
                 type: string
     observability.get_object@200:
-      description: Successful response of retrieving specific Observability Object.
+      description: The API successfully retrieved the specified observability object.
       content:
         application/json:
           schema:
             $ref: '../schemas/observability._common.yaml#/components/schemas/ObservabilityObjectList'
     observability.get_object@404:
-      description: Not Found
+      description: The API could not find the specified observability object.
       content:
         application/json:
           schema:
             $ref: '../schemas/observability._common.yaml#/components/schemas/NotFoundResponse'
     observability.update_object@200:
-      description: Updated
+      description: The API successfully updated the observability object.
       content:
         application/json:
           schema:
             type: object
             properties:
               objectId:
                 type: string
+                description: The unique identifier of the updated observability object.
     observability.update_object@404:
-      description: Not Found
+      description: The API could not find the observability object to update.
       content:
         application/json:
           schema:
             $ref: '../schemas/observability._common.yaml#/components/schemas/NotFoundResponse'
     observability.delete_object@200:
-      description: Deleted
+      description: The API successfully deleted the observability object.
       content:
         application/json:
           schema:
             type: object
             properties:
               deleteResponseList:
+                description: The list of deletion response for each object.
                 type: object
                 additionalProperties:
                   type: string
     observability.delete_object@404:
-      description: Not Found
+      description: The API could not find the observability object to delete.
       content:
         application/json:
           schema:
             $ref: '../schemas/observability._common.yaml#/components/schemas/NotFoundResponse'
     observability.delete_objects@200:
-      description: Deleted
+      description: The API successfully deleted the specified observability objects.
       content:
         application/json:
           schema:
             type: object
             properties:
               deleteResponseList:
+                description: The list of deletion responses for each object.
                 type: object
                 additionalProperties:
                   type: string
                   # example: OK
     observability.delete_objects@404:
-      description: Not Found
+      description: The API could not find one or more observability objects to delete.
       content:
         application/json:
           schema:
             $ref: '../schemas/observability._common.yaml#/components/schemas/NotFoundResponse'
     observability.get_localstats@200:
-      description: Retrieves
+      description: The API successfully retrieved local statistics.
       content:
         text/plain:
           schema:
@@ -184,39 +187,39 @@ components:
     observability.get_object::path.object_id:
       in: path
       name: object_id
-      description: The ID of the Observability Object.
+      description: The ID of the observability object to retrieve.
       required: true
       schema:
         type: string
       style: simple
     observability.update_object::path.object_id:
       in: path
       name: object_id
-      description: The ID of the Observability Object.
+      description: The ID of the observability object to update.
       required: true
       schema:
         type: string
       style: simple
     observability.delete_object::path.object_id:
       in: path
       name: object_id
-      description: The ID of the Observability Object.
+      description: The ID of the observability object to delete.
       required: true
       schema:
         type: string
       style: simple
     observability.delete_objects::query.objectId:
       in: query
       name: objectId
-      description: The ID of a single Observability Object to delete.
+      description: The ID of a single observability object to delete.
       required: false
       schema:
         type: string
       style: form
     observability.delete_objects::query.objectIdList:
       in: query
       name: objectIdList
-      description: A comma-separated list of Observability Object IDs to delete.
+      description: A comma-separated list of observability object IDs to delete.
       required: false
       schema:
         type: string