[Security Assistant] Aligning API Schemas (elastic#188704)

## Summary

This PR aims to address elastic#183825
to ensure all our public API's have a corresponding OpenAPI spec and to
ensure that they are documented as intended.

I've updated the kbn-elastic-assistant-common `yarn openapi:bundle`
script to generate both `ess` and `serverless` artifacts (as per [this
issue](elastic/security-team#9516), which are
now created within the package (instead of `target`), and so are checked
in to `x-pack/packages/kbn-elastic-assistant-common/docs/openapi/`.


This also includes:

- [X] Create OpenAPI specs for the endpoints listed above (see
[issue](elastic#183825)).
  - They had already existed  
- [X] Check if there are any other public endpoints that you own that
don't have OpenAPI specs and add them to the list above.
- All endpoints (public/internal) had specs, but did need to update the
`path`'s to make sure they were consistent with what was registered.
- [X] Make sure the specs you add are valid OpenAPI documents.
- [X] Make sure the specs you add match the actual API contract defined
in the code.
- [X] Mark the endpoints as available in ESS, or Serverless, or in both
offerings.

---
Initial evaluation of routes listed as missing specs in
elastic#183825:

- [X] `POST
/api/elastic_assistant/current_user/conversations/{id}/messages`
Latest/Actual Route:
`/internal/elastic_assistant/current_user/conversations/{id}/messages`
Route Handler:
https://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/plugins/elastic_assistant/server/routes/user_conversations/append_conversation_messages_route.ts#L22
Schema:
https://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L151-L191


- [X]  `POST /api/elastic_assistant/current_user/conversations`
Updated Route: `/api/security_ai_assistant/current_user/conversations`
Route Handler:
https://github.com/elastic/kibana/blob/1d4e9b9b53b5b6dcdc88c08ae5d9858daa483fe0/x-pack/plugins/elastic_assistant/server/routes/user_conversations/create_route.ts#L21
Schema:
https://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L6-L39

- [X]  GET /api/elastic_assistant/current_user/conversations/_find
Updated Route:
`/api/security_ai_assistant/current_user/conversations/_find`
Route Handler:
https://github.com/elastic/kibana/blob/1d4e9b9b53b5b6dcdc88c08ae5d9858daa483fe0/x-pack/plugins/elastic_assistant/server/routes/user_conversations/find_route.ts#L26
Schema:
https://github.com/elastic/kibana/blob/1b872fbf9dc90d3c82a569a9faef9e360fc41171/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/find_conversations_route.schema.yaml#L94-L180

- [X]  DELETE /api/elastic_assistant/current_user/conversations/{id}
Updated Route:
`/api/security_ai_assistant/current_user/conversations/{id}`
Route Handler:
https://github.com/elastic/kibana/blob/1d5cf48a9700ee769f64256c23278fcfd8cecc5d/x-pack/plugins/elastic_assistant/server/routes/user_conversations/delete_route.ts#L19
Schema:
https://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L116-L149

- [X] GET /api/elastic_assistant/current_user/conversations/{id}
Updated Route:
`/api/security_ai_assistant/current_user/conversations/{id}`
Route Handler:
https://github.com/elastic/kibana/blob/1d5cf48a9700ee769f64256c23278fcfd8cecc5d/x-pack/plugins/elastic_assistant/server/routes/user_conversations/read_route.ts#L21
Schema:
https://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L42-L75

- [X]  PUT /api/elastic_assistant/current_user/conversations/{id}
Updated Route:
`/api/security_ai_assistant/current_user/conversations/{id}`
Route Handler:
https://github.com/elastic/kibana/blob/1d5cf48a9700ee769f64256c23278fcfd8cecc5d/x-pack/plugins/elastic_assistant/server/routes/user_conversations/update_route.ts#L24
Schema:
https://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L76-L115


To continue with remaining public routes....

---------

Co-authored-by: kibanamachine <[email protected]>

x-pack/packages/kbn-elastic-assistant-common/docs/openapi/ess/elastic_assistant_api_2023_10_31.bundled.schema.yaml

@@ -0,0 +1,114 @@
+openapi: 3.0.3
+info:
+  description: Manage and interact with Security Assistant resources.
+  title: Security AI Assistant API (Elastic Cloud & self-hosted)
+  version: '2023-10-31'
+servers:
+  - url: 'http://{kibana_host}:{port}'
+    variables:
+      kibana_host:
+        default: localhost
+      port:
+        default: '5601'
+paths:
+  /api/security_ai_assistant/chat/complete:
+    post:
+      description: Creates a model response for the given chat conversation.
+      operationId: ChatComplete
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ChatCompleteProps'
+        required: true
+      responses:
+        '200':
+          content:
+            application/octet-stream:
+              schema:
+                format: binary
+                type: string
+          description: Indicates a successful call.
+        '400':
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+                  message:
+                    type: string
+                  statusCode:
+                    type: number
+          description: Generic Error
+      summary: Creates a model response for the given chat conversation.
+      tags:
+        - Chat Complete API
+components:
+  schemas:
+    ChatCompleteProps:
+      type: object
+      properties:
+        connectorId:
+          type: string
+        conversationId:
+          type: string
+        isStream:
+          type: boolean
+        langSmithApiKey:
+          type: string
+        langSmithProject:
+          type: string
+        messages:
+          items:
+            $ref: '#/components/schemas/ChatMessage'
+          type: array
+        model:
+          type: string
+        persist:
+          type: boolean
+        promptId:
+          type: string
+        responseLanguage:
+          type: string
+      required:
+        - messages
+        - persist
+        - connectorId
+    ChatMessage:
+      description: AI assistant message.
+      type: object
+      properties:
+        content:
+          description: Message content.
+          type: string
+        data:
+          $ref: '#/components/schemas/MessageData'
+          description: ECS object to attach to the context of the message.
+        fields_to_anonymize:
+          items:
+            type: string
+          type: array
+        role:
+          $ref: '#/components/schemas/ChatMessageRole'
+          description: Message role.
+      required:
+        - role
+    ChatMessageRole:
+      description: Message role.
+      enum:
+        - system
+        - user
+        - assistant
+      type: string
+    MessageData:
+      additionalProperties: true
+      type: object
+  securitySchemes:
+    BasicAuth:
+      scheme: basic
+      type: http
+security:
+  - BasicAuth: []
+tags: !<tag:yaml.org,2002:js/undefined> ''