CAMEL-23500: Document camel-openai usage with OpenAI-compatible providers

[k-krawczyk]

Summary

Adds an "OpenAI-Compatible Providers" section to the OpenAI component documentation, with baseUrl-based configuration examples for OpenRouter, Ollama, LM Studio, and vLLM. This makes it discoverable that no separate component is needed to use third-party gateways or local model servers.

Changes

• New == OpenAI-Compatible Providers section in openai-component.adoc:
  • Provider → baseUrl reference table (OpenAI, OpenRouter, Ollama, LM Studio, vLLM)
  • Per-provider examples (Ollama, LM Studio, vLLM)
  • OpenRouter: cross-provider model identifiers and provider routing/fallbacks via additionalBodyProperty (a JSON body value)

Docs-only; no code changes. The docs/components/.../openai-component.adoc page is a symlink to the component source, so only the source file changes.

On the OpenRouter attribution headers

The ticket also asked to document setting OpenRouter's HTTP-Referer / X-Title attribution headers via exchange headers. After checking the code, the component does not currently expose a way to set custom HTTP request headers: the client is built with only apiKey/baseUrl/SSL and the producer calls .create(params) without RequestOptions. So I documented this as a current limitation rather than referencing a non-existent option. I'd suggest a small follow-up enhancement to add a custom request-header option (e.g. additionalRequestHeader.), which the openai-java SDK supports via RequestOptions.putHeader — happy to take that on.

On a dedicated OpenRouter kamelet

The ticket asked to evaluate one. Given baseUrl reduces OpenRouter to a one-line configuration, a dedicated kamelet adds little value over the documented approach, so I'd lean against it.

Reported by Claude Code on behalf of Karol Krawczyk

[gnodet]

Documentation-only addition — well-written guide for using camel-openai with OpenAI-compatible providers (Ollama, LM Studio, vLLM, OpenRouter). The provider routing example for OpenRouter with additionalBodyProperty.provider is particularly useful, and the note about the limitation with custom HTTP headers is transparent.

Good use of AsciiDoc tabs for Java/YAML examples. Provider table is clean and actionable.

LGTM.

Fully automatic review from Claude Code

[github-actions]

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

• First-time contributors require MANUAL approval for the GitHub Actions to run
• You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
• You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
• Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

[github-actions]

🧪 CI tested the following changed modules:

• components/camel-ai/camel-openai

⚠️ Some tests are disabled on GitHub Actions (@DisabledIfSystemProperty(named = "ci.env.name")) and require manual verification:

• components/camel-ai/camel-openai: 6 test(s) disabled on GitHub Actions

All tested modules (8 modules)

• Camel :: AI :: OpenAI
• Camel :: JBang :: MCP
• Camel :: JBang :: Plugin :: Route Parser
• Camel :: JBang :: Plugin :: TUI
• Camel :: JBang :: Plugin :: Validate
• Camel :: Launcher :: Container
• Camel :: YAML DSL :: Validator
• Camel :: YAML DSL :: Validator Maven Plugin

---

⚙️ View full build and test results

[Croway]

Hi @k-krawczyk thanks for your contribution! I added a couple of comments

[davsclaus]

@Croway I cannot see your questions here on github

[Croway]

@davsclaus uh, that is strange, I can see those both in the conversation page, and the Files changed

[k-krawczyk]

@Croway happy to address any concerns — I don't see the comments on the PR either (and there are none
in the JIRA ticket). Could you re-submit the review? Maybe they were left in a pending/draft state.

[Croway]

Can you add the ollama command to install and run llama3.2, as in the example route? and a link to the ollama website?

[Croway]

Please add a link to LM Studio website/documentation

[k-krawczyk]

Thanks @Croway — all four addressed:

1. Ollama — added the ollama run llama3.2 command and a link to https://ollama.com.
2. LM Studio — added a link to https://lmstudio.ai.
3. vLLM — added pip install vllm and the vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000
   command plus a link to docs.vllm.ai. Also added a note on the vllm-mlx variant for Apple Silicon with
   an example vllm-mlx serve mlx-community/Qwen2.5-7B-Instruct-4bit --port 8000.
4. OpenRouter — honest answer: I didn't test against the live OpenRouter API (no account/key at hand).
   The example follows OpenRouter's documented OpenAI-compatible endpoint, and I confirmed in the
   producer code (applyAdditionalBodyProperties / parseJsonOrString) that additionalBodyProperty parses
   JSON-string values into a real JSON object on the request body, so the nested provider field should
   reach OpenRouter correctly. Happy to revise if @orpiske (or anyone with an account) can validate
   end-to-end — or I can sign up and re-test if you'd prefer that before merge.

[davsclaus]

Nice documentation addition — the examples are clear and the honest note about the HTTP header limitation is helpful.

One structural concern: the doc already has two sections covering similar ground that should be consolidated with this new content:

1. Line 259 — === Using Third-Party or Local OpenAI-Compatible Endpoint shows an LM Studio example at localhost:1234/v1, nearly identical to the new LM Studio example in this PR.
2. Line 495 — == Compatibility lists the same providers (OpenAI, Ollama, LM Studio, third-party) that the new section now covers in detail.

With the new section in place, these existing sections become redundant. Could you either remove/consolidate them into the new section, or at least add cross-references so readers aren't presented with three overlapping sections?

This review covers project conventions and documentation structure. It does not replace specialized review tools such as CodeRabbit, Sourcery, or SonarCloud.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.