Support Multiple Clients Using The Same Service (#90)

* Use serviceId as url target if present.

Fixes gh-67

* Code review fixes and improvements

* Fix test

* Add contextId to override bean name of feign client and its configuration.

* Add documentation

* Add contextId example to documentation

docs/src/main/asciidoc/spring-cloud-openfeign.adoc

@@ -73,6 +73,8 @@ in your external configuration (see
 
 A central concept in Spring Cloud's Feign support is that of the named client. Each feign client is part of an ensemble of components that work together to contact a remote server on demand, and the ensemble has a name that you give it as an application developer using the `@FeignClient` annotation. Spring Cloud creates a new ensemble as an
 `ApplicationContext` on demand for each named client using `FeignClientsConfiguration`. This contains (amongst other things) an `feign.Decoder`, a `feign.Encoder`, and a `feign.Contract`.
+It is possible to override the name of that ensemble by using the `contextId`
+attribute of the `@FeignClient` annotation.
 
 Spring Cloud lets you take full control of the feign client by declaring additional configuration (on top of the `FeignClientsConfiguration`) using `@FeignClient`. Example:
 
@@ -90,6 +92,10 @@ NOTE: `FooConfiguration` does not need to be annotated with `@Configuration`. Ho
 
 NOTE: The `serviceId` attribute is now deprecated in favor of the `name` attribute.
 
+NOTE: Using `contextId` attribute of the `@FeignClient` annotation in addition to changing the name of
+the `ApplicationContext` ensemble, it will override the alias of the client name
+and it will be used as part of the name of the configuration bean created for that client.
+
 WARNING: Previously, using the `url` attribute, did not require the `name` attribute. Using `name` is now required.
 
 Placeholders are supported in the `name` and `url` attributes.
@@ -206,6 +212,27 @@ hystrix:
           strategy: SEMAPHORE
 ----
 
+If we want to create multiple feign clients with the same name or url
+so that they would point to the same server but each with a different custom configuration then
+we have to use `contextId` attribute of the `@FeignClient` in order to avoid name
+collision of these configuration beans.
+
+[source,java,indent=0]
+----
+@FeignClient(contextId = "fooClient", name = "stores", configuration = FooConfiguration.class)
+public interface FooClient {
+    //..
+}
+----
+
+[source,java,indent=0]
+----
+@FeignClient(contextId = "barClient", name = "stores", configuration = BarConfiguration.class)
+public interface BarClient {
+    //..
+}
+----
+
 === Creating Feign Clients Manually
 
 In some cases it might be necessary to customize your Feign Clients in a way that is not