[Internal]: Fix incorrect field descriptions in the Security AI Assistant API docs.

[dhru42]

Description

What

Fix incorrect field descriptions in the Security AI Assistant API docs.

Endpoints and Fields to Update

• /api/security_ai_assistant/chat/complete:

  • conversationId → current description: "The ID of the anonymization field." → should describe the actual purpose (e.g., "The unique ID of the conversation.")

• /api/security_ai_assistant/current_user/conversations and
  /api/security_ai_assistant/current_user/conversations/_find:

  • id → current description: "The ID of the anonymization field." → should describe the actual purpose (e.g., "The unique ID of the conversation.")

When

ASAP

Why

To correct misleading API documentation and reduce confusion for users integrating with the Security AI Assistant.

Resources

Link to conversation

Which documentation set does this change impact?

Elastic On-Prem and Cloud (all)

Feature differences

n/a

What release is this request related to?

N/A

Serverless release

ASAP

Collaboration model

The documentation team

Point of contact.

Main contact: @dhru42 @jamesspi

Stakeholders: @jamesspi

[natasha-moore-elastic]

Hi @dhru42, I looked into this – the issue here is that OpenAPI 3.0 doesn't support any sibling fields being used with the $ref keyword. If we look at conversationId in the OAS specs, there is already a description similar to what you're suggesting : https://github.com/elastic/kibana/blob/main/x-pack/platform/packages/shared/kbn-elastic-assistant-common/impl/schemas/chat/post_chat_complete_route.schema.yaml#L134:

but that description isn't rendered and is being overridden by the descrption inside the $ref. This is a limitation of OpenAPI 3.0 – I'm not aware of any workarounds, but there's an ongoing discussion about upgrading Kibana APIs to OpenAPI 3.1.

[natasha-moore-elastic]

Closing – we can only fix this after Kibana APIs are upgraded to OpenAPI 3.1.

[peluja1012]

Hi @natasha-moore-elastic, my recommendation is to keep this open until we fix it so we don't lose track of it.

[peluja1012]

This is a limitation of OpenAPI 3.0

Thanks for looking into it. @YulNaumenko any idea if we could somehow get around this without having to upgrade to OpenAPI 3.1? Found more info about the limitation here. Like @natasha-moore-elastic mentioned, looks like in OpenAPI 3.0 "adjacent keywords" like "description" are ignored when using $refs.

[natasha-moore-elastic]

Moving to backlog – on the Docs side, we can only help fix this after Kibana APIs are upgraded to OpenAPI 3.1.