Apply suggestions from code review

Co-authored-by: Craig Perkins <craig5008@gmail.com>
Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

spec/namespaces/security.yaml

@@ -58,7 +58,7 @@ paths:
       x-distributions-excluded:
         - amazon-managed
         - amazon-serverless
-      description: Retrieves the current `security-dashboards` plugin configuration.
+      description: Retrieves the current values for dynamic security settings for OpenSearch Dashboards.
       responses:
         '200':
           $ref: '#/components/responses/security.get_dashboards_info@200'
@@ -71,7 +71,7 @@ paths:
       x-distributions-excluded:
         - amazon-managed
         - amazon-serverless
-      description: Updates the current `security-dashboards` plugin configuration.
+      description: Retrieves the current values for dynamic security settings for OpenSearch Dashboards
       responses:
         '200':
           $ref: '#/components/responses/security.post_dashboards_info@200'
@@ -100,7 +100,7 @@ paths:
       x-distributions-excluded:
         - amazon-managed
         - amazon-serverless
-      description: Checks to see if the Security plugin is running.
+      description: Checks to see if the Security plugin is initialized.
       parameters:
         - $ref: '#/components/parameters/security.health::query.mode'
       externalDocs:
@@ -160,7 +160,7 @@ paths:
       x-distributions-excluded:
         - amazon-managed
         - amazon-serverless
-      description: Gets the identity information for the user currently logged in. To use this operation, you must have access to this endpoint when authorization at REST layer is enabled.
+      description: Gets the identity information for the user currently logged in. 
       responses:
         '200':
           $ref: '#/components/responses/security.who_am_i@200'
@@ -362,7 +362,7 @@ paths:
       x-distributions-excluded:
         - amazon-managed
         - amazon-serverless
-      description: Creates or replaces APIs permitted for users on the allowlist. Requires a super admin certificate or REST API permissions.
+      description: Creates or replaces APIs permitted for users on the allow list. Requires a super admin certificate or REST API permissions.
       externalDocs:
         url: https://opensearch.org/docs/latest/security/access-control/api/#access-control-for-the-api
       requestBody:
@@ -379,7 +379,7 @@ paths:
       x-distributions-excluded:
         - amazon-managed
         - amazon-serverless
-      description: Updates the current list of APIs accessible for users on the allowlist.
+      description: Updates the current list of APIs accessible for users on the allow list.
       externalDocs:
         url: https://opensearch.org/docs/latest/security/access-control/api/#access-control-for-the-api
       requestBody:
@@ -590,7 +590,7 @@ paths:
       x-distributions-excluded:
         - amazon-managed
         - amazon-serverless
-      description: Retrieve information about the specified user.
+      description: Retrieve information about the specified internal user.
       externalDocs:
         url: https://opensearch.org/docs/latest/security/access-control/api/#get-user
       parameters:
@@ -639,7 +639,7 @@ paths:
       x-distributions-excluded:
         - amazon-managed
         - amazon-serverless
-      description: Deletes the specified user.
+      description: Deletes the specified internal user.
       externalDocs:
         url: https://opensearch.org/docs/latest/security/access-control/api/#delete-user
       parameters:
@@ -685,7 +685,7 @@ paths:
       x-distributions-excluded:
         - amazon-managed
         - amazon-serverless
-      description: Retrieves all distinguished names. Requires super admin or REST API permissions.
+      description: Retrieves all node distinguished names. Requires super admin or REST API permissions.
       externalDocs:
         url: https://opensearch.org/docs/latest/security/access-control/api/#get-distinguished-names
       parameters:
@@ -704,7 +704,7 @@ paths:
       x-distributions-excluded:
         - amazon-managed
         - amazon-serverless
-      description: Bulks updates specified distinguished names. Requires super admin or REST API permissions.
+      description: Bulk updates specified node distinguished names. Requires super admin or REST API permissions.
       externalDocs:
         url: https://opensearch.org/docs/latest/security/access-control/api/#update-all-distinguished-names
       requestBody:
@@ -724,7 +724,7 @@ paths:
       x-distributions-excluded:
         - amazon-managed
         - amazon-serverless
-      description: Retrieves all distinguished names. Requires super admin or REST API permissions.
+      description: Retrieves all node distinguished names. Requires super admin or REST API permissions.
       externalDocs:
         url: https://opensearch.org/docs/latest/security/access-control/api/#get-distinguished-names
       parameters:
@@ -820,7 +820,7 @@ paths:
       x-distributions-excluded:
         - amazon-managed
         - amazon-serverless
-      description: Retrieves all security roles that exist in the cluster.
+      description: Retrieves all roles.
       externalDocs:
         url: https://opensearch.org/docs/latest/security/access-control/api/#get-roles
       responses:
@@ -1051,7 +1051,7 @@ paths:
       x-distributions-excluded:
         - amazon-managed
         - amazon-serverless
-      description: Adds settings or updates the settings for an existing security configuration. Requires super admin or REST API permissions.
+      description: Updates the settings for an existing security configuration. Requires super admin or REST API permissions.
       externalDocs:
         url: https://opensearch.org/docs/latest/security/access-control/api/#update-configuration
       requestBody:
@@ -1087,7 +1087,7 @@ paths:
       x-distributions-excluded:
         - amazon-managed
         - amazon-serverless
-      description: Reloads the HTTP layer's communication certificates.
+      description: Reloads the HTTP communication certificates.
       externalDocs:
         url: https://opensearch.org/docs/latest/security/access-control/api/#reload-http-certificates
       responses:
@@ -1105,7 +1105,7 @@ paths:
       x-distributions-excluded:
         - amazon-managed
         - amazon-serverless
-      description: Reloads the transport layer's communication certificates.
+      description: Reloads the transport communication certificates.
       externalDocs:
         url: https://opensearch.org/docs/latest/security/access-control/api/#reload-transport-certificates
       responses:
@@ -2262,7 +2262,7 @@ components:
     security.create_role_mapping::path.role:
       name: role
       in: path
-      description: The name of the role to create a role mapping.
+      description: The name of the role for which to create a role mapping.
       schema:
         type: string
       required: true
@@ -2339,14 +2339,14 @@ components:
     security.generate_user_token::path.username:
       name: username
       in: path
-      description: The name of the user for whom to give an authorization token.
+      description: The name of the user for whom to issue an authorization token.
       schema:
         type: string
       required: true
     security.generate_user_token_legacy::path.username:
       name: username
       in: path
-      description: The name of the user for whom to give an authorization token.
+      description: The name of the user for whom to issue an authorization token.
       schema:
         type: string
       required: true
@@ -2388,7 +2388,7 @@ components:
     security.get_node_certificates::query.timeout:
       name: timeout
       in: query
-      description: he maximum duration, in seconds, to spend retrieving certificates from all nodes before a timeout.
+      description: The maximum duration, in seconds, to spend retrieving certificates from all nodes before a timeout.
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
       required: false
@@ -2458,7 +2458,7 @@ components:
     security.health::query.mode:
       name: mode
       in: query
-      description: A flag that determines whether to consider the security status before returning a response for a health query response.. For example, `strict` mode indicates service should check the Security plugin status.
+      description: A flag that determines whether to consider the security status before returning a response for a health query response. For example, `strict` mode indicates service should check the Security plugin status.
       schema:
         type: string
       required: false

spec/schemas/security._common.yaml

@@ -307,7 +307,7 @@ components:
       properties:
         config:
           type: array
-          description: A list of configurations to be upgrade.
+          description: A list of configurations to upgrade.
           items:
             type: string