Document when and why to use the name attribute of ServiceConnection

Closes gh-36071

spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/testing.adoc

@@ -1009,9 +1009,19 @@ If you want to create only a subset of the applicable types, you can use the `ty
 ====
 
 By default `Container.getDockerImageName()` is used to obtain the name used to find connection details.
-If you are using a custom docker image, you can use the `name` attribute of `@ServiceConnection` to override it.
+This works as long as Spring Boot is able to get the instance of the `Container`, which is the case when using a `static` field like in the example above.
 
-For example, if you have a `GenericContainer` using a Docker image of `registry.mycompany.com/mirror/myredis`, you'd use `@ServiceConnection(name="redis")` to ensure `RedisConnectionDetails` are created.
+If you're using a `@Bean` method, Spring Boot won't call the bean method to get the Docker image name, because this would cause eager initialization issues.
+Instead, the return type of the bean method is used to find out which connection detail should be used.
+This works as long as you're using typed containers, e.g. `Neo4jContainer` or `RabbitMQContainer`.
+This stops working if you're using `GenericContainer`, e.g. with Redis, as shown in the following example:
+
+include::code:MyRedisConfiguration[]
+
+Spring Boot can't tell from `GenericContainer` which container image is used, so the `name` attribute from `@ServiceConnection` must be used to provide that hint.
+
+You can also can use the `name` attribute of `@ServiceConnection` to override which connection detail will be used, for example when using custom images.
+If you are using the Docker image `registry.mycompany.com/mirror/myredis`, you'd use `@ServiceConnection(name="redis")` to ensure `RedisConnectionDetails` are created.
 
 
 
@@ -1064,6 +1074,8 @@ You can now launch `TestMyApplication` as you would any regular Java `main` meth
 
 TIP: You can use the Maven goal `spring-boot:test-run` or the Gradle task `bootTestRun` to do this from the command line.
 
+
+
 [[features.testing.testcontainers.at-development-time.dynamic-properties]]
 ===== Contributing Dynamic Properties at Development Time
 If you want to contribute dynamic properties at development time from your `Container` `@Bean` methods, you can do so by injecting a `DynamicPropertyRegistry`.

spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/features/testing/testcontainers/serviceconnections/MyRedisConfiguration.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2012-2023 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.docs.features.testing.testcontainers.serviceconnections;
+
+import org.testcontainers.containers.GenericContainer;
+
+import org.springframework.boot.test.context.TestConfiguration;
+import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
+import org.springframework.context.annotation.Bean;
+
+@TestConfiguration(proxyBeanMethods = false)
+public class MyRedisConfiguration {
+
+	@Bean
+	@ServiceConnection(name = "redis")
+	public GenericContainer<?> redisContainer() {
+		return new GenericContainer<>("redis:7");
+	}
+
+}

spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/features/testing/testcontainers/serviceconnections/MyRedisConfiguration.kt

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2012-2023 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.docs.features.testing.testcontainers.serviceconnections
+
+import org.springframework.boot.test.context.TestConfiguration
+import org.springframework.boot.testcontainers.service.connection.ServiceConnection
+import org.springframework.context.annotation.Bean;
+import org.testcontainers.containers.GenericContainer
+
+@TestConfiguration(proxyBeanMethods = false)
+class MyRedisConfiguration {
+
+	@Bean
+	@ServiceConnection(name = "redis")
+	fun redisContainer(): GenericContainer<*> {
+		return GenericContainer("redis:7")
+	}
+
+}