GH-3187: Replace Spring environment variables with custom alternatives

Fixes: #3187

This commit addresses the issue with Spring environment variables that directly
mirror Spring AI application properties, which can confuse users into thinking
they should always set environment variables that match Spring property names.

Instead, we've replaced all instances of SPRING_* prefixed environment variables
in the documentation with custom-named alternatives that are referenced using
Spring Expression Language (SpEL) or retrieved programmatically.

Each documentation section now shows multiple configuration approaches:

- Direct property setting in application.properties/yml
- Using custom environment variables with SpEL
- Accessing environment variables programmatically

This gives users more flexibility while making it clear that using SPRING_*
prefixed environment variables is not required or recommended.

Signed-off-by: Soby Chacko <[email protected]>

Author: sobychacko

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/anthropic-chat.adoc

@@ -10,14 +10,42 @@ Spring AI provides dedicated xref:api/chat/bedrock-converse.adoc[Amazon Bedrock
 
 == Prerequisites
 
-You will need to create an API key on Anthropic portal.
-Create an account at https://console.anthropic.com/dashboard[Anthropic API dashboard] and generate the api key on the https://console.anthropic.com/settings/keys[Get API Keys] page.
+You will need to create an API key on the Anthropic portal.
+
+Create an account at https://console.anthropic.com/dashboard[Anthropic API dashboard] and generate the API key on the https://console.anthropic.com/settings/keys[Get API Keys] page.
+
 The Spring AI project defines a configuration property named `spring.ai.anthropic.api-key` that you should set to the value of the `API Key` obtained from anthropic.com.
-Exporting an environment variable is one way to set that configuration property:
 
-[source,shell]
+You can set this configuration property in your `application.properties` file:
+
+[source,properties]
+----
+spring.ai.anthropic.api-key=<your-anthropic-api-key>
+----
+
+For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference a custom environment variable:
+
+[source,yaml]
+----
+# In application.yml
+spring:
+  ai:
+    anthropic:
+      api-key: ${ANTHROPIC_API_KEY}
+----
+
+[source,bash]
+----
+# In your environment or .env file
+export ANTHROPIC_API_KEY=<your-anthropic-api-key>
+----
+
+You can also set this configuration programmatically in your application code:
+
+[source,java]
 ----
-export SPRING_AI_ANTHROPIC_API_KEY=<INSERT KEY HERE>
+// Retrieve API key from a secure source or environment variable
+String apiKey = System.getenv("ANTHROPIC_API_KEY");
 ----
 
 === Add Repositories and BOM

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/azure-openai-chat.adoc

@@ -14,15 +14,35 @@ To access models using an API key, obtain your Azure OpenAI `endpoint` and `api-
 
 Spring AI defines two configuration properties:
 
-1. `spring.ai.azure.openai.api-key`: Set this to the value the `API Key` obtained from Azure.
+1. `spring.ai.azure.openai.api-key`: Set this to the value of the `API Key` obtained from Azure.
 2. `spring.ai.azure.openai.endpoint`: Set this to the endpoint URL obtained when provisioning your model in Azure.
 
-You can set these configuration properties by exporting environment variables:
+You can set these configuration properties in your `application.properties` or `application.yml` file:
 
-[source,shell]
+[source,properties]
 ----
-export SPRING_AI_AZURE_OPENAI_API_KEY=<INSERT AZURE KEY HERE>
-export SPRING_AI_AZURE_OPENAI_ENDPOINT=<INSERT ENDPOINT URL HERE>
+spring.ai.azure.openai.api-key=<your-azure-api-key>
+spring.ai.azure.openai.endpoint=<your-azure-endpoint-url>
+----
+
+For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference custom environment variables:
+
+[source,yaml]
+----
+# In application.yml
+spring:
+  ai:
+    azure:
+      openai:
+        api-key: ${AZURE_OPENAI_API_KEY}
+        endpoint: ${AZURE_OPENAI_ENDPOINT}
+----
+
+[source,bash]
+----
+# In your environment or .env file
+export AZURE_OPENAI_API_KEY=<your-azure-openai-api-key>
+export AZURE_OPENAI_ENDPOINT=<your-azure-openai-endpoint-url>
 ----
 
 === OpenAI Key
@@ -31,9 +51,34 @@ To authenticate with the OpenAI service (not Azure), provide an OpenAI API key.
 
 When using this approach, set the `spring.ai.azure.openai.chat.options.deployment-name` property to the name of the https://platform.openai.com/docs/models[OpenAI model] you wish to use.
 
-[source,shell]
+In your application configuration:
+
+[source,properties]
+----
+spring.ai.azure.openai.openai-api-key=<your-azure-openai-key>
+spring.ai.azure.openai.chat.options.deployment-name=<openai-model-name>
+----
+
+Using environment variables with SpEL:
+
+[source,yaml]
+----
+# In application.yml
+spring:
+  ai:
+    azure:
+      openai:
+        openai-api-key: ${AZURE_OPENAI_API_KEY}
+        chat:
+          options:
+            deployment-name: ${AZURE_OPENAI_MODEL_NAME}
+----
+
+[source,bash]
 ----
-export SPRING_AI_AZURE_OPENAI_OPENAI_API_KEY=<INSERT OPENAI KEY HERE>
+# In your environment or .env file
+export AZURE_OPENAI_API_KEY=<your-openai-key>
+export AZURE_OPENAI_MODEL_NAME=<openai-model-name>
 ----
 
 === Microsoft Entra ID

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/deepseek-chat.adoc

@@ -5,13 +5,41 @@ Spring AI supports the various AI language models from DeepSeek. You can interac
 == Prerequisites
 
 You will need to create an API key with DeepSeek to access DeepSeek language models.
+
 Create an account at https://platform.deepseek.com/sign_up[DeepSeek registration page] and generate a token on the https://platform.deepseek.com/api_keys[API Keys page].
-The Spring AI project defines a configuration property named `spring.ai.deepseek.api-key` that you should set to the value of the `API Key` obtained from the https://platform.deepseek.com/api_keys[API Keys page].
-Exporting an environment variable is one way to set this configuration property:
 
-[source,shell]
+The Spring AI project defines a configuration property named `spring.ai.deepseek.api-key` that you should set to the value of the `API Key` obtained from the API Keys page.
+
+You can set this configuration property in your `application.properties` file:
+
+[source,properties]
+----
+spring.ai.deepseek.api-key=<your-deepseek-api-key>
+----
+
+For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference a custom environment variable:
+
+[source,yaml]
+----
+# In application.yml
+spring:
+  ai:
+    deepseek:
+      api-key: ${DEEPSEEK_API_KEY}
+----
+
+[source,bash]
+----
+# In your environment or .env file
+export DEEPSEEK_API_KEY=<your-deepseek-api-key>
+----
+
+You can also set this configuration programmatically in your application code:
+
+[source,java]
 ----
-export SPRING_AI_DEEPSEEK_API_KEY=<INSERT KEY HERE>
+// Retrieve API key from a secure source or environment variable
+String apiKey = System.getenv("DEEPSEEK_API_KEY");
 ----
 
 === Add Repositories and BOM

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/groq-chat.adoc

@@ -18,21 +18,55 @@ for examples of using Groq with Spring AI.
 
 == Prerequisites
 
-* Create an API Key.
-Please visit https://console.groq.com/keys[here] to create an API Key.
+* **Create an API Key**:
+Visit https://console.groq.com/keys[here] to create an API Key.
 The Spring AI project defines a configuration property named `spring.ai.openai.api-key` that you should set to the value of the `API Key` obtained from groq.com.
-* Set the Groq URL. 
+
+* **Set the Groq URL**:
 You have to set the `spring.ai.openai.base-url` property to `https://api.groq.com/openai`.
-* Select a https://console.groq.com/docs/models[Groq Model].
-Use the `spring.ai.openai.chat.options.model=<model name>` property to set the Model.
 
-Exporting an environment variable is one way to set that configuration property:
+* **Select a Groq Model**:
+Use the `spring.ai.openai.chat.model=<model name>` property to select from the available https://console.groq.com/docs/models[Groq Models].
+
+You can set these configuration properties in your `application.properties` file:
+
+[source,properties]
+----
+spring.ai.openai.api-key=<your-groq-api-key>
+spring.ai.openai.base-url=https://api.groq.com/openai
+spring.ai.openai.chat.model=llama3-70b-8192
+----
+
+For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference custom environment variables:
 
-[source,shell]
+[source,yaml]
+----
+# In application.yml
+spring:
+  ai:
+    openai:
+      api-key: ${GROQ_API_KEY}
+      base-url: ${GROQ_BASE_URL}
+      chat:
+        model: ${GROQ_MODEL}
+----
+
+[source,bash]
+----
+# In your environment or .env file
+export GROQ_API_KEY=<your-groq-api-key>
+export GROQ_BASE_URL=https://api.groq.com/openai
+export GROQ_MODEL=llama3-70b-8192
+----
+
+You can also set these configurations programmatically in your application code:
+
+[source,java]
 ----
-export SPRING_AI_OPENAI_API_KEY=<INSERT GROQ API KEY HERE>
-export SPRING_AI_OPENAI_BASE_URL=https://api.groq.com/openai
-export SPRING_AI_OPENAI_CHAT_MODEL=llama3-70b-8192
+// Retrieve configuration from secure sources or environment variables
+String apiKey = System.getenv("GROQ_API_KEY");
+String baseUrl = System.getenv("GROQ_BASE_URL");
+String model = System.getenv("GROQ_MODEL");
 ----
 
 === Add Repositories and BOM

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/huggingface.adoc

@@ -10,15 +10,49 @@ TIP: For a complete and up-to-date list of supported models and architectures, s
 
 You will need to create an Inference Endpoint on Hugging Face and create an API token to access the endpoint.
 Further details can be found link:https://huggingface.co/docs/inference-endpoints/index[here].
-The Spring AI project defines a configuration property named `spring.ai.huggingface.chat.api-key` that you should set to the value of the API token obtained from Hugging Face.
-There is also a configuration property named `spring.ai.huggingface.chat.url` that you should set to the inference endpoint URL obtained when provisioning your model in Hugging Face.
-You can find this on the Inference Endpoint's UI link:https://ui.endpoints.huggingface.co/[here].
-Exporting environment variables is one way to set these configuration properties:
 
-[source,shell]
+The Spring AI project defines two configuration properties:
+
+1. `spring.ai.huggingface.chat.api-key`: Set this to the value of the API token obtained from Hugging Face.
+2. `spring.ai.huggingface.chat.url`: Set this to the inference endpoint URL obtained when provisioning your model in Hugging Face.
+
+You can find your inference endpoint URL on the Inference Endpoint's UI link:https://ui.endpoints.huggingface.co/[here].
+
+You can set these configuration properties in your `application.properties` file:
+
+[source,properties]
+----
+spring.ai.huggingface.chat.api-key=<your-huggingface-api-key>
+spring.ai.huggingface.chat.url=<your-inference-endpoint-url>
+----
+
+For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference custom environment variables:
+
+[source,yaml]
+----
+# In application.yml
+spring:
+  ai:
+    huggingface:
+      chat:
+        api-key: ${HUGGINGFACE_API_KEY}
+        url: ${HUGGINGFACE_ENDPOINT_URL}
+----
+
+[source,bash]
+----
+# In your environment or .env file
+export HUGGINGFACE_API_KEY=<your-huggingface-api-key>
+export HUGGINGFACE_ENDPOINT_URL=<your-inference-endpoint-url>
+----
+
+You can also set these configurations programmatically in your application code:
+
+[source,java]
 ----
-export SPRING_AI_HUGGINGFACE_CHAT_API_KEY=<INSERT KEY HERE>
-export SPRING_AI_HUGGINGFACE_CHAT_URL=<INSERT INFERENCE ENDPOINT URL HERE>
+// Retrieve API key and endpoint URL from secure sources or environment variables
+String apiKey = System.getenv("HUGGINGFACE_API_KEY");
+String endpointUrl = System.getenv("HUGGINGFACE_ENDPOINT_URL");
 ----
 
 === Add Repositories and BOM

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/minimax-chat.adoc

@@ -7,12 +7,39 @@ Spring AI supports the various AI language models from MiniMax. You can interact
 You will need to create an API with MiniMax to access MiniMax language models.
 
 Create an account at https://www.minimaxi.com/login[MiniMax registration page] and generate the token on the https://www.minimaxi.com/user-center/basic-information/interface-key[API Keys page].
-The Spring AI project defines a configuration property named `spring.ai.minimax.api-key` that you should set to the value of the `API Key` obtained from https://www.minimaxi.com/user-center/basic-information/interface-key[API Keys page].
-Exporting an environment variable is one way to set that configuration property:
 
-[source,shell]
+The Spring AI project defines a configuration property named `spring.ai.minimax.api-key` that you should set to the value of the `API Key` obtained from the API Keys page.
+
+You can set this configuration property in your `application.properties` file:
+
+[source,properties]
+----
+spring.ai.minimax.api-key=<your-minimax-api-key>
+----
+
+For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference an environment variable:
+
+[source,yaml]
+----
+# In application.yml
+spring:
+  ai:
+    minimax:
+      api-key: ${MINIMAX_API_KEY}
+----
+
+[source,bash]
+----
+# In your environment or .env file
+export MINIMAX_API_KEY=<your-minimax-api-key>
+----
+
+You can also set this configuration programmatically in your application code:
+
+[source,java]
 ----
-export SPRING_AI_MINIMAX_API_KEY=<INSERT KEY HERE>
+// Retrieve API key from a secure source or environment variable
+String apiKey = System.getenv("MINIMAX_API_KEY");
 ----
 
 === Add Repositories and BOM
@@ -298,4 +325,4 @@ Flux<ChatResponse> streamResponse = chatModel.stream(new Prompt(this.messages, t
 ==== MiniMaxApi Samples
 * The link:https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-minimax/src/test/java/org/springframework/ai/minimax/api/MiniMaxApiIT.java[MiniMaxApiIT.java] test provides some general examples how to use the lightweight library.
 
-* The link:https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-minimax/src/test/java/org/springframework/ai/minimax/api/MiniMaxApiToolFunctionCallIT.java[MiniMaxApiToolFunctionCallIT.java] test shows how to use the low-level API to call tool functions.>
+* The link:https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-minimax/src/test/java/org/springframework/ai/minimax/api/MiniMaxApiToolFunctionCallIT.java[MiniMaxApiToolFunctionCallIT.java] test shows how to use the low-level API to call tool functions.>

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/mistralai-chat.adoc

@@ -8,13 +8,41 @@ Check the xref:_openai_api_compatibility[OpenAI API compatibility] section to le
 == Prerequisites
 
 You will need to create an API with Mistral AI to access Mistral AI language models.
+
 Create an account at https://auth.mistral.ai/ui/registration[Mistral AI registration page] and generate the token on the https://console.mistral.ai/api-keys/[API Keys page].
+
 The Spring AI project defines a configuration property named `spring.ai.mistralai.api-key` that you should set to the value of the `API Key` obtained from console.mistral.ai.
-Exporting an environment variable is one way to set that configuration property:
 
-[source,shell]
+You can set this configuration property in your `application.properties` file:
+
+[source,properties]
+----
+spring.ai.mistralai.api-key=<your-mistralai-api-key>
+----
+
+For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference a custom environment variable:
+
+[source,yaml]
+----
+# In application.yml
+spring:
+  ai:
+    mistralai:
+      api-key: ${MISTRALAI_API_KEY}
+----
+
+[source,bash]
+----
+# In your environment or .env file
+export MISTRALAI_API_KEY=<your-mistralai-api-key>
+----
+
+You can also set this configuration programmatically in your application code:
+
+[source,java]
 ----
-export SPRING_AI_MISTRALAI_API_KEY=<INSERT KEY HERE>
+// Retrieve API key from a secure source or environment variable
+String apiKey = System.getenv("MISTRALAI_API_KEY");
 ----
 
 === Add Repositories and BOM