Inference API documentation missing content

[jonathan-buttner]

The transition to the new docs system which bases the content on the comments and examples within the specification is missing information from the old docs system for the Inference API.

I'll list a few examples below but I suspect that we'll need to go through each page of the old docs of the inference API and compare it to the new docs to determine the extent of what is missing.

Chat Completion API

The 8.x docs are here: https://github.com/elastic/elasticsearch/blob/8.x/docs/reference/inference/chat-completion-inference.asciidoc?plain=1

The new docs are based on the content here: https://github.com/elastic/elasticsearch-specification/blob/main/specification/inference/chat_completion_unified/UnifiedRequest.ts#L25

Examples of things that are missing

• The Important callout here: https://github.com/elastic/elasticsearch/blob/8.x/docs/reference/inference/chat-completion-inference.asciidoc?plain=1#L7-L9
• The description: https://github.com/elastic/elasticsearch/blob/8.x/docs/reference/inference/chat-completion-inference.asciidoc?plain=1#L34-L35
• The required cluster privileges
• The Note: https://github.com/elastic/elasticsearch/blob/8.x/docs/reference/inference/chat-completion-inference.asciidoc?plain=1#L38-L44
• We had organized certain fields around the type of messages that can be sent (Assistant, System, Tool, etc) and we had examples embedded in the sections for those objects: https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-inference-chat-completion-unified#operation-inference-chat-completion-unified-body-application-json-messages

There are probably more things but those are the ones that immediately stand out.

[szabosteve]

I started to work on this issue here: #4346
The PR partially addresses this issue:

• adds the important callout back
• expands the API description
• adds the note back
• expands param descriptions,
• provides working examples.

However, documenting the parameters by message types is not trivial. I'll address that part in a follow-up PR.