Improves Security AI Assistant API docs content (elastic#192254)

## Summary Resolves elastic/security-docs-internal#36 by improving the Security AI Assistant API docs content. Adds missing and improves existing operation summaries and operation descriptions to adhere to our [OAS standards](https://elasticco.atlassian.net/wiki/spaces/DOC/pages/450494532/API+reference+docs). --------- Co-authored-by: kibanamachine <[email protected]>
kapral18 · Sep 6, 2024 · 842caa2 · 842caa2
1 parent d3c3b28
commit 842caa2
Show file tree

Hide file tree

Showing 9 changed files with 62 additions and 58 deletions.
diff --git a/...ic-assistant-common/docs/openapi/ess/elastic_assistant_api_2023_10_31.bundled.schema.yaml b/...ic-assistant-common/docs/openapi/ess/elastic_assistant_api_2023_10_31.bundled.schema.yaml
@@ -14,8 +14,9 @@ paths:
   /api/security_ai_assistant/anonymization_fields/_bulk_action:
     post:
       description: >-
-        The bulk action is applied to all anonymization fields that match the
-        filter or to the list of anonymization fields by their IDs.
+        Apply a bulk action to multiple anonymization fields. The bulk action is
+        applied to all anonymization fields that match the filter or to the list
+        of anonymization fields by their IDs.
       operationId: PerformAnonymizationFieldsBulkAction
       requestBody:
         content:
@@ -63,13 +64,13 @@ paths:
                   statusCode:
                     type: number
           description: Generic Error
-      summary: Applies a bulk action to multiple anonymization fields
+      summary: Apply a bulk action to anonymization fields
       tags:
         - Security AI Assistant API
         - Bulk API
   /api/security_ai_assistant/anonymization_fields/_find:
     get:
-      description: Finds anonymization fields that match the given query.
+      description: Get a list of all anonymization fields.
       operationId: FindAnonymizationFields
       parameters:
         - in: query
@@ -149,13 +150,13 @@ paths:
                   statusCode:
                     type: number
           description: Generic Error
-      summary: Finds anonymization fields that match the given query.
+      summary: Get anonymization fields
       tags:
         - Security AI Assistant API
         - AnonymizationFields API
   /api/security_ai_assistant/chat/complete:
     post:
-      description: Creates a model response for the given chat conversation.
+      description: Create a model response for the given chat conversation.
       operationId: ChatComplete
       requestBody:
         content:
@@ -184,13 +185,13 @@ paths:
                   statusCode:
                     type: number
           description: Generic Error
-      summary: Creates a model response for the given chat conversation.
+      summary: Create a model response
       tags:
         - Security AI Assistant API
         - Chat Complete API
   /api/security_ai_assistant/current_user/conversations:
     post:
-      description: Create a conversation
+      description: Create a new Security AI Assistant conversation.
       operationId: CreateConversation
       requestBody:
         content:
@@ -224,7 +225,7 @@ paths:
         - Conversation API
   /api/security_ai_assistant/current_user/conversations/_find:
     get:
-      description: Finds conversations that match the given query.
+      description: Get a list of all conversations for the current user.
       operationId: FindConversations
       parameters:
         - in: query
@@ -304,13 +305,13 @@ paths:
                   statusCode:
                     type: number
           description: Generic Error
-      summary: Finds conversations that match the given query.
+      summary: Get conversations
       tags:
         - Security AI Assistant API
         - Conversations API
   '/api/security_ai_assistant/current_user/conversations/{id}':
     delete:
-      description: Deletes a single conversation using the `id` field.
+      description: Delete an existing conversation using the conversation ID.
       operationId: DeleteConversation
       parameters:
         - description: The conversation's `id` value.
@@ -339,12 +340,12 @@ paths:
                   statusCode:
                     type: number
           description: Generic Error
-      summary: Deletes a single conversation using the `id` field.
+      summary: Delete a conversation
       tags:
         - Security AI Assistant API
         - Conversation API
     get:
-      description: Read a single conversation
+      description: Get the details of an existing conversation using the conversation ID.
       operationId: ReadConversation
       parameters:
         - description: The conversation's `id` value.
@@ -373,12 +374,12 @@ paths:
                   statusCode:
                     type: number
           description: Generic Error
-      summary: Read a single conversation
+      summary: Get a conversation
       tags:
         - Security AI Assistant API
         - Conversations API
     put:
-      description: Update a single conversation
+      description: Update an existing conversation using the conversation ID.
       operationId: UpdateConversation
       parameters:
         - description: The conversation's `id` value.
@@ -420,8 +421,9 @@ paths:
   /api/security_ai_assistant/prompts/_bulk_action:
     post:
       description: >-
-        The bulk action is applied to all prompts that match the filter or to
-        the list of prompts by their IDs.
+        Apply a bulk action to multiple prompts. The bulk action is applied to
+        all prompts that match the filter or to the list of prompts by their
+        IDs.
       operationId: PerformPromptsBulkAction
       requestBody:
         content:
@@ -469,13 +471,13 @@ paths:
                   statusCode:
                     type: number
           description: Generic Error
-      summary: Applies a bulk action to multiple prompts
+      summary: Apply a bulk action to prompts
       tags:
         - Security AI Assistant API
         - Bulk API
   /api/security_ai_assistant/prompts/_find:
     get:
-      description: Finds prompts that match the given query.
+      description: Get a list of all prompts.
       operationId: FindPrompts
       parameters:
         - in: query
@@ -555,7 +557,7 @@ paths:
                   statusCode:
                     type: number
           description: Generic Error
-      summary: Finds prompts that match the given query.
+      summary: Get prompts
       tags:
         - Security AI Assistant API
         - Prompts API

diff --git a/...stant-common/docs/openapi/serverless/elastic_assistant_api_2023_10_31.bundled.schema.yaml b/...stant-common/docs/openapi/serverless/elastic_assistant_api_2023_10_31.bundled.schema.yaml
@@ -14,8 +14,9 @@ paths:
   /api/security_ai_assistant/anonymization_fields/_bulk_action:
     post:
       description: >-
-        The bulk action is applied to all anonymization fields that match the
-        filter or to the list of anonymization fields by their IDs.
+        Apply a bulk action to multiple anonymization fields. The bulk action is
+        applied to all anonymization fields that match the filter or to the list
+        of anonymization fields by their IDs.
       operationId: PerformAnonymizationFieldsBulkAction
       requestBody:
         content:
@@ -63,13 +64,13 @@ paths:
                   statusCode:
                     type: number
           description: Generic Error
-      summary: Applies a bulk action to multiple anonymization fields
+      summary: Apply a bulk action to anonymization fields
       tags:
         - Security AI Assistant API
         - Bulk API
   /api/security_ai_assistant/anonymization_fields/_find:
     get:
-      description: Finds anonymization fields that match the given query.
+      description: Get a list of all anonymization fields.
       operationId: FindAnonymizationFields
       parameters:
         - in: query
@@ -149,13 +150,13 @@ paths:
                   statusCode:
                     type: number
           description: Generic Error
-      summary: Finds anonymization fields that match the given query.
+      summary: Get anonymization fields
       tags:
         - Security AI Assistant API
         - AnonymizationFields API
   /api/security_ai_assistant/chat/complete:
     post:
-      description: Creates a model response for the given chat conversation.
+      description: Create a model response for the given chat conversation.
       operationId: ChatComplete
       requestBody:
         content:
@@ -184,13 +185,13 @@ paths:
                   statusCode:
                     type: number
           description: Generic Error
-      summary: Creates a model response for the given chat conversation.
+      summary: Create a model response
       tags:
         - Security AI Assistant API
         - Chat Complete API
   /api/security_ai_assistant/current_user/conversations:
     post:
-      description: Create a conversation
+      description: Create a new Security AI Assistant conversation.
       operationId: CreateConversation
       requestBody:
         content:
@@ -224,7 +225,7 @@ paths:
         - Conversation API
   /api/security_ai_assistant/current_user/conversations/_find:
     get:
-      description: Finds conversations that match the given query.
+      description: Get a list of all conversations for the current user.
       operationId: FindConversations
       parameters:
         - in: query
@@ -304,13 +305,13 @@ paths:
                   statusCode:
                     type: number
           description: Generic Error
-      summary: Finds conversations that match the given query.
+      summary: Get conversations
       tags:
         - Security AI Assistant API
         - Conversations API
   '/api/security_ai_assistant/current_user/conversations/{id}':
     delete:
-      description: Deletes a single conversation using the `id` field.
+      description: Delete an existing conversation using the conversation ID.
       operationId: DeleteConversation
       parameters:
         - description: The conversation's `id` value.
@@ -339,12 +340,12 @@ paths:
                   statusCode:
                     type: number
           description: Generic Error
-      summary: Deletes a single conversation using the `id` field.
+      summary: Delete a conversation
       tags:
         - Security AI Assistant API
         - Conversation API
     get:
-      description: Read a single conversation
+      description: Get the details of an existing conversation using the conversation ID.
       operationId: ReadConversation
       parameters:
         - description: The conversation's `id` value.
@@ -373,12 +374,12 @@ paths:
                   statusCode:
                     type: number
           description: Generic Error
-      summary: Read a single conversation
+      summary: Get a conversation
       tags:
         - Security AI Assistant API
         - Conversations API
     put:
-      description: Update a single conversation
+      description: Update an existing conversation using the conversation ID.
       operationId: UpdateConversation
       parameters:
         - description: The conversation's `id` value.
@@ -420,8 +421,9 @@ paths:
   /api/security_ai_assistant/prompts/_bulk_action:
     post:
       description: >-
-        The bulk action is applied to all prompts that match the filter or to
-        the list of prompts by their IDs.
+        Apply a bulk action to multiple prompts. The bulk action is applied to
+        all prompts that match the filter or to the list of prompts by their
+        IDs.
       operationId: PerformPromptsBulkAction
       requestBody:
         content:
@@ -469,13 +471,13 @@ paths:
                   statusCode:
                     type: number
           description: Generic Error
-      summary: Applies a bulk action to multiple prompts
+      summary: Apply a bulk action to prompts
       tags:
         - Security AI Assistant API
         - Bulk API
   /api/security_ai_assistant/prompts/_find:
     get:
-      description: Finds prompts that match the given query.
+      description: Get a list of all prompts.
       operationId: FindPrompts
       parameters:
         - in: query
@@ -555,7 +557,7 @@ paths:
                   statusCode:
                     type: number
           description: Generic Error
-      summary: Finds prompts that match the given query.
+      summary: Get prompts
       tags:
         - Security AI Assistant API
         - Prompts API

diff --git a/...common/impl/schemas/anonymization_fields/bulk_crud_anonymization_fields_route.schema.yaml b/...common/impl/schemas/anonymization_fields/bulk_crud_anonymization_fields_route.schema.yaml
@@ -8,8 +8,8 @@ paths:
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       operationId: PerformAnonymizationFieldsBulkAction
-      summary: Applies a bulk action to multiple anonymization fields
-      description: The bulk action is applied to all anonymization fields that match the filter or to the list of anonymization fields by their IDs.
+      summary: Apply a bulk action to anonymization fields
+      description: Apply a bulk action to multiple anonymization fields. The bulk action is applied to all anonymization fields that match the filter or to the list of anonymization fields by their IDs.
       tags:
         - Bulk API
       requestBody:

diff --git a/...tant-common/impl/schemas/anonymization_fields/find_anonymization_fields_route.schema.yaml b/...tant-common/impl/schemas/anonymization_fields/find_anonymization_fields_route.schema.yaml
@@ -8,8 +8,8 @@ paths:
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       operationId: FindAnonymizationFields
-      description: Finds anonymization fields that match the given query.
-      summary: Finds anonymization fields that match the given query.
+      description: Get a list of all anonymization fields.
+      summary: Get anonymization fields
       tags:
         - AnonymizationFields API
       parameters:

diff --git a/...kages/kbn-elastic-assistant-common/impl/schemas/chat/post_chat_complete_route.schema.yaml b/...kages/kbn-elastic-assistant-common/impl/schemas/chat/post_chat_complete_route.schema.yaml
@@ -8,8 +8,8 @@ paths:
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       operationId: ChatComplete
-      description: Creates a model response for the given chat conversation.
-      summary: Creates a model response for the given chat conversation.
+      description: Create a model response for the given chat conversation.
+      summary: Create a model response
       tags:
         - Chat Complete API
       requestBody:

diff --git a/...n-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml b/...n-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml
@@ -8,7 +8,7 @@ paths:
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       operationId: CreateConversation
-      description: Create a conversation
+      description: Create a new Security AI Assistant conversation.
       summary: Create a conversation
       tags:
         - Conversation API
@@ -44,8 +44,8 @@ paths:
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       operationId: ReadConversation
-      description: Read a single conversation
-      summary: Read a single conversation
+      description: Get the details of an existing conversation using the conversation ID.
+      summary: Get a conversation
       tags:
         - Conversations API
       parameters:
@@ -79,7 +79,7 @@ paths:
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       operationId: UpdateConversation
-      description: Update a single conversation
+      description: Update an existing conversation using the conversation ID.
       summary: Update a conversation
       tags:
         - Conversation API
@@ -120,8 +120,8 @@ paths:
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       operationId: DeleteConversation
-      description: Deletes a single conversation using the `id` field.
-      summary: Deletes a single conversation using the `id` field.
+      description: Delete an existing conversation using the conversation ID.
+      summary: Delete a conversation
       tags:
         - Conversation API
       parameters:

diff --git a/...-elastic-assistant-common/impl/schemas/conversations/find_conversations_route.schema.yaml b/...-elastic-assistant-common/impl/schemas/conversations/find_conversations_route.schema.yaml
@@ -8,8 +8,8 @@ paths:
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       operationId: FindConversations
-      description: Finds conversations that match the given query.
-      summary: Finds conversations that match the given query.
+      description: Get a list of all conversations for the current user.
+      summary: Get conversations
       tags:
         - Conversations API
       parameters:

diff --git a/...ges/kbn-elastic-assistant-common/impl/schemas/prompts/bulk_crud_prompts_route.schema.yaml b/...ges/kbn-elastic-assistant-common/impl/schemas/prompts/bulk_crud_prompts_route.schema.yaml
@@ -8,8 +8,8 @@ paths:
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       operationId: PerformPromptsBulkAction
-      summary: Applies a bulk action to multiple prompts
-      description: The bulk action is applied to all prompts that match the filter or to the list of prompts by their IDs.
+      summary: Apply a bulk action to prompts
+      description: Apply a bulk action to multiple prompts. The bulk action is applied to all prompts that match the filter or to the list of prompts by their IDs.
       tags:
         - Bulk API
       requestBody: