SpringCloud/spring-cloud-openfeign
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Sync docs from master to gh-pages

Browse Source
This commit is contained in:
buildmaster
2019-09-10 13:30:21 +00:00
parent a9838dd5c1
commit b2fd4339b7
3 changed files with 165 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
reference/html/README.html
View File

@@ -95,21 +95,21 @@ $(addBlockSwitches);
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#_features">Features</a></li>
<li><a href="#_building">Building</a>
<li><a href="#features">1. Features</a></li>
<li><a href="#building">2. Building</a>
<ul class="sectlevel2">
<li><a href="#_basic_compile_and_test">Basic Compile and Test</a></li>
<li><a href="#_documentation">Documentation</a></li>
<li><a href="#_working_with_the_code">Working with the code</a></li>
<li><a href="#basic-compile-and-test">2.1. Basic Compile and Test</a></li>
<li><a href="#documentation">2.2. Documentation</a></li>
<li><a href="#working-with-the-code">2.3. Working with the code</a></li>
</ul>
</li>
<li><a href="#_contributing">Contributing</a>
<li><a href="#contributing">3. Contributing</a>
<ul class="sectlevel2">
<li><a href="#_sign_the_contributor_license_agreement">Sign the Contributor License Agreement</a></li>
<li><a href="#_code_of_conduct">Code of Conduct</a></li>
<li><a href="#_code_conventions_and_housekeeping">Code Conventions and Housekeeping</a></li>
<li><a href="#_checkstyle">Checkstyle</a></li>
<li><a href="#_ide_setup">IDE setup</a></li>
<li><a href="#sign-the-contributor-license-agreement">3.1. Sign the Contributor License Agreement</a></li>
<li><a href="#code-of-conduct">3.2. Code of Conduct</a></li>
<li><a href="#code-conventions-and-housekeeping">3.3. Code Conventions and Housekeeping</a></li>
<li><a href="#checkstyle">3.4. Checkstyle</a></li>
<li><a href="#ide-setup">3.5. IDE setup</a></li>
</ul>
</li>
</ul>
@@ -134,7 +134,7 @@ and binding to the Spring Environment and other Spring programming model idioms.
</div>
</div>
<div class="sect1">
<h2 id="_features"><a class="link" href="#_features">Features</a></h2>
<h2 id="features"><a class="anchor" href="#features"></a><a class="link" href="#features">1. Features</a></h2>
<div class="sectionbody">
<div class="ulist">
<ul>
@@ -146,10 +146,10 @@ and binding to the Spring Environment and other Spring programming model idioms.
</div>
</div>
<div class="sect1">
<h2 id="_building"><a class="link" href="#_building">Building</a></h2>
<h2 id="building"><a class="anchor" href="#building"></a><a class="link" href="#building">2. Building</a></h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_basic_compile_and_test"><a class="link" href="#_basic_compile_and_test">Basic Compile and Test</a></h3>
<h3 id="basic-compile-and-test"><a class="anchor" href="#basic-compile-and-test"></a><a class="link" href="#basic-compile-and-test">2.1. Basic Compile and Test</a></h3>
<div class="paragraph">
<p>To build the source you will need to install JDK 1.8.</p>
</div>
@@ -227,7 +227,7 @@ If all else fails, build with the command from <code>.travis.yml</code> (usually
</div>
</div>
<div class="sect2">
<h3 id="_documentation"><a class="link" href="#_documentation">Documentation</a></h3>
<h3 id="documentation"><a class="anchor" href="#documentation"></a><a class="link" href="#documentation">2.2. Documentation</a></h3>
<div class="paragraph">
<p>The spring-cloud-build module has a "docs" profile, and if you switch
that on it will try to build asciidoc sources from
@@ -240,7 +240,7 @@ a modified file in the correct place. Just commit it and push the change.</p>
</div>
</div>
<div class="sect2">
<h3 id="_working_with_the_code"><a class="link" href="#_working_with_the_code">Working with the code</a></h3>
<h3 id="working-with-the-code"><a class="anchor" href="#working-with-the-code"></a><a class="link" href="#working-with-the-code">2.3. Working with the code</a></h3>
<div class="paragraph">
<p>If you don&#8217;t have an IDE preference we would recommend that you use
<a href="https://www.springsource.com/developer/sts">Spring Tools Suite</a> or
@@ -249,7 +249,7 @@ a modified file in the correct place. Just commit it and push the change.</p>
should also work without issue as long as they use Maven 3.3.3 or better.</p>
</div>
<div class="sect3">
<h4 id="_importing_into_eclipse_with_m2eclipse"><a class="link" href="#_importing_into_eclipse_with_m2eclipse">Importing into eclipse with m2eclipse</a></h4>
<h4 id="importing-into-eclipse-with-m2eclipse"><a class="anchor" href="#importing-into-eclipse-with-m2eclipse"></a><a class="link" href="#importing-into-eclipse-with-m2eclipse">2.3.1. Importing into eclipse with m2eclipse</a></h4>
<div class="paragraph">
<p>We recommend the <a href="https://eclipse.org/m2e/">m2eclipse</a> eclipse plugin when working with
eclipse. If you don&#8217;t already have m2eclipse installed it is available from the "eclipse
@@ -276,7 +276,7 @@ pom into your <code>settings.xml</code>.
</div>
</div>
<div class="sect3">
<h4 id="_importing_into_eclipse_without_m2eclipse"><a class="link" href="#_importing_into_eclipse_without_m2eclipse">Importing into eclipse without m2eclipse</a></h4>
<h4 id="importing-into-eclipse-without-m2eclipse"><a class="anchor" href="#importing-into-eclipse-without-m2eclipse"></a><a class="link" href="#importing-into-eclipse-without-m2eclipse">2.3.2. Importing into eclipse without m2eclipse</a></h4>
<div class="paragraph">
<p>If you prefer not to use m2eclipse you can generate eclipse project metadata using the
following command:</p>
@@ -295,7 +295,7 @@ from the <code>file</code> menu.</p>
</div>
</div>
<div class="sect1">
<h2 id="_contributing"><a class="link" href="#_contributing">Contributing</a></h2>
<h2 id="contributing"><a class="anchor" href="#contributing"></a><a class="link" href="#contributing">3. Contributing</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>Spring Cloud is released under the non-restrictive Apache 2.0 license,
@@ -305,7 +305,7 @@ to contribute even something trivial please do not hesitate, but
follow the guidelines below.</p>
</div>
<div class="sect2">
<h3 id="_sign_the_contributor_license_agreement"><a class="link" href="#_sign_the_contributor_license_agreement">Sign the Contributor License Agreement</a></h3>
<h3 id="sign-the-contributor-license-agreement"><a class="anchor" href="#sign-the-contributor-license-agreement"></a><a class="link" href="#sign-the-contributor-license-agreement">3.1. Sign the Contributor License Agreement</a></h3>
<div class="paragraph">
<p>Before we accept a non-trivial patch or pull request we will need you to sign the
<a href="https://cla.pivotal.io/sign/spring">Contributor License Agreement</a>.
@@ -316,7 +316,7 @@ given the ability to merge pull requests.</p>
</div>
</div>
<div class="sect2">
<h3 id="_code_of_conduct"><a class="link" href="#_code_of_conduct">Code of Conduct</a></h3>
<h3 id="code-of-conduct"><a class="anchor" href="#code-of-conduct"></a><a class="link" href="#code-of-conduct">3.2. Code of Conduct</a></h3>
<div class="paragraph">
<p>This project adheres to the Contributor Covenant <a href="https://github.com/spring-cloud/spring-cloud-build/blob/master/docs/src/main/asciidoc/code-of-conduct.adoc">code of
conduct</a>. By participating, you are expected to uphold this code. Please report
@@ -324,7 +324,7 @@ unacceptable behavior to <a href="mailto:spring-code-of-conduct@pivotal.io">spri
</div>
</div>
<div class="sect2">
<h3 id="_code_conventions_and_housekeeping"><a class="link" href="#_code_conventions_and_housekeeping">Code Conventions and Housekeeping</a></h3>
<h3 id="code-conventions-and-housekeeping"><a class="anchor" href="#code-conventions-and-housekeeping"></a><a class="link" href="#code-conventions-and-housekeeping">3.3. Code Conventions and Housekeeping</a></h3>
<div class="paragraph">
<p>None of these is essential for a pull request, but they will all help. They can also be
added after the original pull request but before a merge.</p>
@@ -372,7 +372,7 @@ message (where XXXX is the issue number).</p>
</div>
</div>
<div class="sect2">
<h3 id="_checkstyle"><a class="link" href="#_checkstyle">Checkstyle</a></h3>
<h3 id="checkstyle"><a class="anchor" href="#checkstyle"></a><a class="link" href="#checkstyle">3.4. Checkstyle</a></h3>
<div class="paragraph">
<p>Spring Cloud Build comes with a set of checkstyle rules. You can find them in the <code>spring-cloud-build-tools</code> module. The most notable files under the module are:</p>
</div>
@@ -405,7 +405,7 @@ message (where XXXX is the issue number).</p>
</table>
</div>
<div class="sect3">
<h4 id="_checkstyle_configuration"><a class="link" href="#_checkstyle_configuration">Checkstyle configuration</a></h4>
<h4 id="checkstyle-configuration"><a class="anchor" href="#checkstyle-configuration"></a><a class="link" href="#checkstyle-configuration">3.4.1. Checkstyle configuration</a></h4>
<div class="paragraph">
<p>Checkstyle rules are <strong>disabled by default</strong>. To add checkstyle to your project just define the following properties and plugins.</p>
</div>
@@ -475,11 +475,11 @@ message (where XXXX is the issue number).</p>
<div class="content">
<pre>&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE suppressions PUBLIC
"-//Puppy Crawl//DTD Suppressions 1.1//EN"
"https://www.puppycrawl.com/dtds/suppressions_1_1.dtd"&gt;
"-//Puppy Crawl//DTD Suppressions 1.1//EN"
"https://www.puppycrawl.com/dtds/suppressions_1_1.dtd"&gt;
&lt;suppressions&gt;
&lt;suppress files=".*ConfigServerApplication\.java" checks="HideUtilityClassConstructor"/&gt;
&lt;suppress files=".*ConfigClientWatch\.java" checks="LineLengthCheck"/&gt;
&lt;suppress files=".*ConfigServerApplication\.java" checks="HideUtilityClassConstructor"/&gt;
&lt;suppress files=".*ConfigClientWatch\.java" checks="LineLengthCheck"/&gt;
&lt;/suppressions&gt;</pre>
</div>
</div>
@@ -495,9 +495,9 @@ $ touch .springformat</code></pre>
</div>
</div>
<div class="sect2">
<h3 id="_ide_setup"><a class="link" href="#_ide_setup">IDE setup</a></h3>
<h3 id="ide-setup"><a class="anchor" href="#ide-setup"></a><a class="link" href="#ide-setup">3.5. IDE setup</a></h3>
<div class="sect3">
<h4 id="_intellij_idea"><a class="link" href="#_intellij_idea">Intellij IDEA</a></h4>
<h4 id="intellij-idea"><a class="anchor" href="#intellij-idea"></a><a class="link" href="#intellij-idea">3.5.1. Intellij IDEA</a></h4>
<div class="paragraph">
<p>In order to setup Intellij you should import our coding conventions, inspection profiles and set up the checkstyle plugin.
The following files can be found in the <a href="https://github.com/spring-cloud/spring-cloud-build/tree/master/spring-cloud-build-tools">Spring Cloud Build</a> project.</p>
@@ -569,15 +569,15 @@ The following files can be found in the <a href="https://github.com/spring-cloud
</div>
</div>
<div class="paragraph">
<p>Go to <code>File</code> &#8594; <code>Settings</code> &#8594; <code>Other settings</code> &#8594; <code>Checkstyle</code>. There click on the <code>+</code> icon in the <code>Configuration file</code> section. There, you&#8217;ll have to define where the checkstyle rules should be picked from. In the image above, we&#8217;ve picked the rules from the cloned Spring Cloud Build repository. However, you can point to the Spring Cloud Build&#8217;s GitHub repository (e.g. for the <code>checkstyle.xml</code> : <code><a href="https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle.xml" class="bare">https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle.xml</a></code>). We need to provide the following variables:</p>
<p>Go to <code>File</code> &#8594; <code>Settings</code> &#8594; <code>Other settings</code> &#8594; <code>Checkstyle</code>. There click on the <code>+</code> icon in the <code>Configuration file</code> section. There, you&#8217;ll have to define where the checkstyle rules should be picked from. In the image above, we&#8217;ve picked the rules from the cloned Spring Cloud Build repository. However, you can point to the Spring Cloud Build&#8217;s GitHub repository (e.g. for the <code>checkstyle.xml</code> : <code><a href="https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle.xml" class="bare">raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle.xml</a></code>). We need to provide the following variables:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>checkstyle.header.file</code> - please point it to the Spring Cloud Build&#8217;s, <code>spring-cloud-build-tools/src/main/resources/checkstyle/checkstyle-header.txt</code> file either in your cloned repo or via the <code><a href="https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle-header.txt" class="bare">https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle-header.txt</a></code> URL.</p>
<p><code>checkstyle.header.file</code> - please point it to the Spring Cloud Build&#8217;s, <code>spring-cloud-build-tools/src/main/resources/checkstyle/checkstyle-header.txt</code> file either in your cloned repo or via the <code><a href="https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle-header.txt" class="bare">raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle-header.txt</a></code> URL.</p>
</li>
<li>
<p><code>checkstyle.suppressions.file</code> - default suppressions. Please point it to the Spring Cloud Build&#8217;s, <code>spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml</code> file either in your cloned repo or via the <code><a href="https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml" class="bare">https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml</a></code> URL.</p>
<p><code>checkstyle.suppressions.file</code> - default suppressions. Please point it to the Spring Cloud Build&#8217;s, <code>spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml</code> file either in your cloned repo or via the <code><a href="https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml" class="bare">raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml</a></code> URL.</p>
</li>
<li>
<p><code>checkstyle.additional.suppressions.file</code> - this variable corresponds to suppressions in your local project. E.g. you&#8217;re working on <code>spring-cloud-contract</code>. Then point to the <code>project-root/src/checkstyle/checkstyle-suppressions.xml</code> folder. Example for <code>spring-cloud-contract</code> would be: <code>/home/username/spring-cloud-contract/src/checkstyle/checkstyle-suppressions.xml</code>.</p>

123
reference/html/index.html
View File

@@ -96,21 +96,22 @@ $(addBlockSwitches);
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#spring-cloud-feign">Declarative REST Client: Feign</a>
<li><a href="#spring-cloud-feign">1. Declarative REST Client: Feign</a>
<ul class="sectlevel2">
<li><a href="#netflix-feign-starter">How to Include Feign</a></li>
<li><a href="#spring-cloud-feign-overriding-defaults">Overriding Feign Defaults</a></li>
<li><a href="#_creating_feign_clients_manually">Creating Feign Clients Manually</a></li>
<li><a href="#spring-cloud-feign-hystrix">Feign Hystrix Support</a></li>
<li><a href="#spring-cloud-feign-hystrix-fallback">Feign Hystrix Fallbacks</a></li>
<li><a href="#_feign_and_primary">Feign and <code>@Primary</code></a></li>
<li><a href="#spring-cloud-feign-inheritance">Feign Inheritance Support</a></li>
<li><a href="#_feign_requestresponse_compression">Feign request/response compression</a></li>
<li><a href="#_feign_logging">Feign logging</a></li>
<li><a href="#_feign_querymap_support">Feign @QueryMap support</a></li>
<li><a href="#_hateoas_support">HATEOAS support</a></li>
<li><a href="#netflix-feign-starter">1.1. How to Include Feign</a></li>
<li><a href="#spring-cloud-feign-overriding-defaults">1.2. Overriding Feign Defaults</a></li>
<li><a href="#creating-feign-clients-manually">1.3. Creating Feign Clients Manually</a></li>
<li><a href="#spring-cloud-feign-hystrix">1.4. Feign Hystrix Support</a></li>
<li><a href="#spring-cloud-feign-hystrix-fallback">1.5. Feign Hystrix Fallbacks</a></li>
<li><a href="#feign-and-primary">1.6. Feign and <code>@Primary</code></a></li>
<li><a href="#spring-cloud-feign-inheritance">1.7. Feign Inheritance Support</a></li>
<li><a href="#feign-requestresponse-compression">1.8. Feign request/response compression</a></li>
<li><a href="#feign-logging">1.9. Feign logging</a></li>
<li><a href="#feign-querymap-support">1.10. Feign @QueryMap support</a></li>
<li><a href="#hateoas-support">1.11. HATEOAS support</a></li>
</ul>
</li>
<li><a href="#configuration-properties">2. Configuration properties</a></li>
</ul>
</div>
</div>
@@ -127,13 +128,13 @@ and binding to the Spring Environment and other Spring programming model idioms.
</div>
</div>
<div class="sect1">
<h2 id="spring-cloud-feign"><a class="link" href="#spring-cloud-feign">Declarative REST Client: Feign</a></h2>
<h2 id="spring-cloud-feign"><a class="anchor" href="#spring-cloud-feign"></a><a class="link" href="#spring-cloud-feign">1. Declarative REST Client: Feign</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p><a href="https://github.com/Netflix/feign">Feign</a> is a declarative web service client. It makes writing web service clients easier. To use Feign create an interface and annotate it. It has pluggable annotation support including Feign annotations and JAX-RS annotations. Feign also supports pluggable encoders and decoders. Spring Cloud adds support for Spring MVC annotations and for using the same <code>HttpMessageConverters</code> used by default in Spring Web. Spring Cloud integrates Ribbon and Eureka to provide a load balanced http client when using Feign.</p>
</div>
<div class="sect2">
<h3 id="netflix-feign-starter"><a class="link" href="#netflix-feign-starter">How to Include Feign</a></h3>
<h3 id="netflix-feign-starter"><a class="anchor" href="#netflix-feign-starter"></a><a class="link" href="#netflix-feign-starter">1.1. How to Include Feign</a></h3>
<div class="paragraph">
<p>To include Feign in your project use the starter with group <code>org.springframework.cloud</code>
and artifact id <code>spring-cloud-starter-openfeign</code>. See the <a href="https://projects.spring.io/spring-cloud/">Spring Cloud Project page</a>
@@ -188,7 +189,7 @@ in your external configuration (see
</div>
</div>
<div class="sect2">
<h3 id="spring-cloud-feign-overriding-defaults"><a class="link" href="#spring-cloud-feign-overriding-defaults">Overriding Feign Defaults</a></h3>
<h3 id="spring-cloud-feign-overriding-defaults"><a class="anchor" href="#spring-cloud-feign-overriding-defaults"></a><a class="link" href="#spring-cloud-feign-overriding-defaults">1.2. Overriding Feign Defaults</a></h3>
<div class="paragraph">
<p>A central concept in Spring Cloud&#8217;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 <code>@FeignClient</code> annotation. Spring Cloud creates a new ensemble as an
<code>ApplicationContext</code> on demand for each named client using <code>FeignClientsConfiguration</code>. This contains (amongst other things) an <code>feign.Decoder</code>, a <code>feign.Encoder</code>, and a <code>feign.Contract</code>.
@@ -456,7 +457,7 @@ public interface BarClient {
</div>
</div>
<div class="sect2">
<h3 id="_creating_feign_clients_manually"><a class="link" href="#_creating_feign_clients_manually">Creating Feign Clients Manually</a></h3>
<h3 id="creating-feign-clients-manually"><a class="anchor" href="#creating-feign-clients-manually"></a><a class="link" href="#creating-feign-clients-manually">1.3. Creating Feign Clients Manually</a></h3>
<div class="paragraph">
<p>In some cases it might be necessary to customize your Feign Clients in a way that is not
possible using the methods above. In this case you can create Clients using the
@@ -469,25 +470,25 @@ a separate request interceptor.</p>
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Import(FeignClientsConfiguration.class)
class FooController {
private FooClient fooClient;
private FooClient fooClient;
private FooClient adminClient;
private FooClient adminClient;
@Autowired
public FooController(Decoder decoder, Encoder encoder, Client client, Contract contract) {
this.fooClient = Feign.builder().client(client)
.encoder(encoder)
.decoder(decoder)
.contract(contract)
.requestInterceptor(new BasicAuthRequestInterceptor("user", "user"))
.target(FooClient.class, "https://PROD-SVC");
@Autowired
public FooController(Decoder decoder, Encoder encoder, Client client, Contract contract) {
this.fooClient = Feign.builder().client(client)
.encoder(encoder)
.decoder(decoder)
.contract(contract)
.requestInterceptor(new BasicAuthRequestInterceptor("user", "user"))
.target(FooClient.class, "https://PROD-SVC");
this.adminClient = Feign.builder().client(client)
.encoder(encoder)
.decoder(decoder)
.contract(contract)
.requestInterceptor(new BasicAuthRequestInterceptor("admin", "admin"))
.target(FooClient.class, "https://PROD-SVC");
this.adminClient = Feign.builder().client(client)
.encoder(encoder)
.decoder(decoder)
.contract(contract)
.requestInterceptor(new BasicAuthRequestInterceptor("admin", "admin"))
.target(FooClient.class, "https://PROD-SVC");
}
}</code></pre>
</div>
@@ -533,7 +534,7 @@ the default Feign native annotations.
</div>
</div>
<div class="sect2">
<h3 id="spring-cloud-feign-hystrix"><a class="link" href="#spring-cloud-feign-hystrix">Feign Hystrix Support</a></h3>
<h3 id="spring-cloud-feign-hystrix"><a class="anchor" href="#spring-cloud-feign-hystrix"></a><a class="link" href="#spring-cloud-feign-hystrix">1.4. Feign Hystrix Support</a></h3>
<div class="paragraph">
<p>If Hystrix is on the classpath and <code>feign.hystrix.enabled=true</code>, Feign will wrap all methods with a circuit breaker. Returning a <code>com.netflix.hystrix.HystrixCommand</code> is also available. This lets you use reactive patterns (with a call to <code>.toObservable()</code> or <code>.observe()</code> or asynchronous use (with a call to <code>.queue()</code>).</p>
</div>
@@ -544,11 +545,11 @@ the default Feign native annotations.
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Configuration
public class FooConfiguration {
@Bean
@Scope("prototype")
public Feign.Builder feignBuilder() {
return Feign.builder();
}
@Bean
@Scope("prototype")
public Feign.Builder feignBuilder() {
return Feign.builder();
}
}</code></pre>
</div>
</div>
@@ -568,7 +569,7 @@ favor for an opt-in approach.
</div>
</div>
<div class="sect2">
<h3 id="spring-cloud-feign-hystrix-fallback"><a class="link" href="#spring-cloud-feign-hystrix-fallback">Feign Hystrix Fallbacks</a></h3>
<h3 id="spring-cloud-feign-hystrix-fallback"><a class="anchor" href="#spring-cloud-feign-hystrix-fallback"></a><a class="link" href="#spring-cloud-feign-hystrix-fallback">1.5. Feign Hystrix Fallbacks</a></h3>
<div class="paragraph">
<p>Hystrix supports the notion of a fallback: a default code path that is executed when they circuit is open or there is an error. To enable fallbacks for a given <code>@FeignClient</code> set the <code>fallback</code> attribute to the class name that implements the fallback. You also need to declare your implementation as a Spring bean.</p>
</div>
@@ -595,21 +596,21 @@ static class HystrixClientFallback implements HystrixClient {
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@FeignClient(name = "hello", fallbackFactory = HystrixClientFallbackFactory.class)
protected interface HystrixClient {
@RequestMapping(method = RequestMethod.GET, value = "/hello")
Hello iFailSometimes();
@RequestMapping(method = RequestMethod.GET, value = "/hello")
Hello iFailSometimes();
}
@Component
static class HystrixClientFallbackFactory implements FallbackFactory&lt;HystrixClient&gt; {
@Override
public HystrixClient create(Throwable cause) {
return new HystrixClient() {
@Override
public Hello iFailSometimes() {
return new Hello("fallback; reason was: " + cause.getMessage());
}
};
}
@Override
public HystrixClient create(Throwable cause) {
return new HystrixClient() {
@Override
public Hello iFailSometimes() {
return new Hello("fallback; reason was: " + cause.getMessage());
}
};
}
}</code></pre>
</div>
</div>
@@ -627,7 +628,7 @@ There is a limitation with the implementation of fallbacks in Feign and how Hyst
</div>
</div>
<div class="sect2">
<h3 id="_feign_and_primary"><a class="link" href="#_feign_and_primary">Feign and <code>@Primary</code></a></h3>
<h3 id="feign-and-primary"><a class="anchor" href="#feign-and-primary"></a><a class="link" href="#feign-and-primary">1.6. Feign and <code>@Primary</code></a></h3>
<div class="paragraph">
<p>When using Feign with Hystrix fallbacks, there are multiple beans in the <code>ApplicationContext</code> of the same type. This will cause <code>@Autowired</code> to not work because there isn&#8217;t exactly one bean, or one marked as primary. To work around this, Spring Cloud Netflix marks all Feign instances as <code>@Primary</code>, so Spring Framework will know which bean to inject. In some cases, this may not be desirable. To turn off this behavior set the <code>primary</code> attribute of <code>@FeignClient</code> to false.</p>
</div>
@@ -635,13 +636,13 @@ There is a limitation with the implementation of fallbacks in Feign and how Hyst
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@FeignClient(name = "hello", primary = false)
public interface HelloClient {
// methods here
// methods here
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="spring-cloud-feign-inheritance"><a class="link" href="#spring-cloud-feign-inheritance">Feign Inheritance Support</a></h3>
<h3 id="spring-cloud-feign-inheritance"><a class="anchor" href="#spring-cloud-feign-inheritance"></a><a class="link" href="#spring-cloud-feign-inheritance">1.7. Feign Inheritance Support</a></h3>
<div class="paragraph">
<p>Feign supports boilerplate apis via single-inheritance interfaces.
This allows grouping common operations into convenient base interfaces.</p>
@@ -693,7 +694,7 @@ mapping is not inherited).
</div>
</div>
<div class="sect2">
<h3 id="_feign_requestresponse_compression"><a class="link" href="#_feign_requestresponse_compression">Feign request/response compression</a></h3>
<h3 id="feign-requestresponse-compression"><a class="anchor" href="#feign-requestresponse-compression"></a><a class="link" href="#feign-requestresponse-compression">1.8. Feign request/response compression</a></h3>
<div class="paragraph">
<p>You may consider enabling the request or response GZIP compression for your
Feign requests. You can do this by enabling one of the properties:</p>
@@ -719,7 +720,7 @@ feign.compression.request.min-request-size=2048</code></pre>
</div>
</div>
<div class="sect2">
<h3 id="_feign_logging"><a class="link" href="#_feign_logging">Feign logging</a></h3>
<h3 id="feign-logging"><a class="anchor" href="#feign-logging"></a><a class="link" href="#feign-logging">1.9. Feign logging</a></h3>
<div class="paragraph">
<p>A logger is created for each Feign client created. By default the name of the logger is the full class name of the interface used to create the Feign client. Feign logging only responds to the <code>DEBUG</code> level.</p>
</div>
@@ -764,7 +765,7 @@ public class FooConfiguration {
</div>
</div>
<div class="sect2">
<h3 id="_feign_querymap_support"><a class="link" href="#_feign_querymap_support">Feign @QueryMap support</a></h3>
<h3 id="feign-querymap-support"><a class="anchor" href="#feign-querymap-support"></a><a class="link" href="#feign-querymap-support">1.10. Feign @QueryMap support</a></h3>
<div class="paragraph">
<p>The OpenFeign <code>@QueryMap</code> annotation provides support for POJOs to be used as
GET parameter maps. Unfortunately, the default OpenFeign QueryMap annotation is
@@ -806,7 +807,7 @@ public interface DemoTemplate {
</div>
</div>
<div class="sect2">
<h3 id="_hateoas_support"><a class="link" href="#_hateoas_support">HATEOAS support</a></h3>
<h3 id="hateoas-support"><a class="anchor" href="#hateoas-support"></a><a class="link" href="#hateoas-support">1.11. HATEOAS support</a></h3>
<div class="paragraph">
<p>Spring provides some APIs to create REST representations that follow the <a href="https://en.wikipedia.org/wiki/HATEOAS">HATEOAS</a> principle, <a href="https://spring.io/projects/spring-hateoas">Spring Hateoas</a> and <a href="https://spring.io/projects/spring-data-rest">Spring Data REST</a>.</p>
</div>
@@ -831,6 +832,14 @@ public interface DemoTemplate {
</div>
</div>
</div>
<div class="sect1">
<h2 id="configuration-properties"><a class="anchor" href="#configuration-properties"></a><a class="link" href="#configuration-properties">2. Configuration properties</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>To see the list of all Sleuth related configuration properties please check <a href="appendix.html">the Appendix page</a>.</p>
</div>
</div>
</div>
</div>
<script type="text/javascript" src="js/tocbot/tocbot.min.js"></script>
<script type="text/javascript" src="js/toc.js"></script>

123
reference/html/spring-cloud-openfeign.html
View File

@@ -96,21 +96,22 @@ $(addBlockSwitches);
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#spring-cloud-feign">Declarative REST Client: Feign</a>
<li><a href="#spring-cloud-feign">1. Declarative REST Client: Feign</a>
<ul class="sectlevel2">
<li><a href="#netflix-feign-starter">How to Include Feign</a></li>
<li><a href="#spring-cloud-feign-overriding-defaults">Overriding Feign Defaults</a></li>
<li><a href="#_creating_feign_clients_manually">Creating Feign Clients Manually</a></li>
<li><a href="#spring-cloud-feign-hystrix">Feign Hystrix Support</a></li>
<li><a href="#spring-cloud-feign-hystrix-fallback">Feign Hystrix Fallbacks</a></li>
<li><a href="#_feign_and_primary">Feign and <code>@Primary</code></a></li>
<li><a href="#spring-cloud-feign-inheritance">Feign Inheritance Support</a></li>
<li><a href="#_feign_requestresponse_compression">Feign request/response compression</a></li>
<li><a href="#_feign_logging">Feign logging</a></li>
<li><a href="#_feign_querymap_support">Feign @QueryMap support</a></li>
<li><a href="#_hateoas_support">HATEOAS support</a></li>
<li><a href="#netflix-feign-starter">1.1. How to Include Feign</a></li>
<li><a href="#spring-cloud-feign-overriding-defaults">1.2. Overriding Feign Defaults</a></li>
<li><a href="#creating-feign-clients-manually">1.3. Creating Feign Clients Manually</a></li>
<li><a href="#spring-cloud-feign-hystrix">1.4. Feign Hystrix Support</a></li>
<li><a href="#spring-cloud-feign-hystrix-fallback">1.5. Feign Hystrix Fallbacks</a></li>
<li><a href="#feign-and-primary">1.6. Feign and <code>@Primary</code></a></li>
<li><a href="#spring-cloud-feign-inheritance">1.7. Feign Inheritance Support</a></li>
<li><a href="#feign-requestresponse-compression">1.8. Feign request/response compression</a></li>
<li><a href="#feign-logging">1.9. Feign logging</a></li>
<li><a href="#feign-querymap-support">1.10. Feign @QueryMap support</a></li>
<li><a href="#hateoas-support">1.11. HATEOAS support</a></li>
</ul>
</li>
<li><a href="#configuration-properties">2. Configuration properties</a></li>
</ul>
</div>
</div>
@@ -127,13 +128,13 @@ and binding to the Spring Environment and other Spring programming model idioms.
</div>
</div>
<div class="sect1">
<h2 id="spring-cloud-feign"><a class="link" href="#spring-cloud-feign">Declarative REST Client: Feign</a></h2>
<h2 id="spring-cloud-feign"><a class="anchor" href="#spring-cloud-feign"></a><a class="link" href="#spring-cloud-feign">1. Declarative REST Client: Feign</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p><a href="https://github.com/Netflix/feign">Feign</a> is a declarative web service client. It makes writing web service clients easier. To use Feign create an interface and annotate it. It has pluggable annotation support including Feign annotations and JAX-RS annotations. Feign also supports pluggable encoders and decoders. Spring Cloud adds support for Spring MVC annotations and for using the same <code>HttpMessageConverters</code> used by default in Spring Web. Spring Cloud integrates Ribbon and Eureka to provide a load balanced http client when using Feign.</p>
</div>
<div class="sect2">
<h3 id="netflix-feign-starter"><a class="link" href="#netflix-feign-starter">How to Include Feign</a></h3>
<h3 id="netflix-feign-starter"><a class="anchor" href="#netflix-feign-starter"></a><a class="link" href="#netflix-feign-starter">1.1. How to Include Feign</a></h3>
<div class="paragraph">
<p>To include Feign in your project use the starter with group <code>org.springframework.cloud</code>
and artifact id <code>spring-cloud-starter-openfeign</code>. See the <a href="https://projects.spring.io/spring-cloud/">Spring Cloud Project page</a>
@@ -188,7 +189,7 @@ in your external configuration (see
</div>
</div>
<div class="sect2">
<h3 id="spring-cloud-feign-overriding-defaults"><a class="link" href="#spring-cloud-feign-overriding-defaults">Overriding Feign Defaults</a></h3>
<h3 id="spring-cloud-feign-overriding-defaults"><a class="anchor" href="#spring-cloud-feign-overriding-defaults"></a><a class="link" href="#spring-cloud-feign-overriding-defaults">1.2. Overriding Feign Defaults</a></h3>
<div class="paragraph">
<p>A central concept in Spring Cloud&#8217;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 <code>@FeignClient</code> annotation. Spring Cloud creates a new ensemble as an
<code>ApplicationContext</code> on demand for each named client using <code>FeignClientsConfiguration</code>. This contains (amongst other things) an <code>feign.Decoder</code>, a <code>feign.Encoder</code>, and a <code>feign.Contract</code>.
@@ -456,7 +457,7 @@ public interface BarClient {
</div>
</div>
<div class="sect2">
<h3 id="_creating_feign_clients_manually"><a class="link" href="#_creating_feign_clients_manually">Creating Feign Clients Manually</a></h3>
<h3 id="creating-feign-clients-manually"><a class="anchor" href="#creating-feign-clients-manually"></a><a class="link" href="#creating-feign-clients-manually">1.3. Creating Feign Clients Manually</a></h3>
<div class="paragraph">
<p>In some cases it might be necessary to customize your Feign Clients in a way that is not
possible using the methods above. In this case you can create Clients using the
@@ -469,25 +470,25 @@ a separate request interceptor.</p>
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Import(FeignClientsConfiguration.class)
class FooController {
private FooClient fooClient;
private FooClient fooClient;
private FooClient adminClient;
private FooClient adminClient;
@Autowired
public FooController(Decoder decoder, Encoder encoder, Client client, Contract contract) {
this.fooClient = Feign.builder().client(client)
.encoder(encoder)
.decoder(decoder)
.contract(contract)
.requestInterceptor(new BasicAuthRequestInterceptor("user", "user"))
.target(FooClient.class, "https://PROD-SVC");
@Autowired
public FooController(Decoder decoder, Encoder encoder, Client client, Contract contract) {
this.fooClient = Feign.builder().client(client)
.encoder(encoder)
.decoder(decoder)
.contract(contract)
.requestInterceptor(new BasicAuthRequestInterceptor("user", "user"))
.target(FooClient.class, "https://PROD-SVC");
this.adminClient = Feign.builder().client(client)
.encoder(encoder)
.decoder(decoder)
.contract(contract)
.requestInterceptor(new BasicAuthRequestInterceptor("admin", "admin"))
.target(FooClient.class, "https://PROD-SVC");
this.adminClient = Feign.builder().client(client)
.encoder(encoder)
.decoder(decoder)
.contract(contract)
.requestInterceptor(new BasicAuthRequestInterceptor("admin", "admin"))
.target(FooClient.class, "https://PROD-SVC");
}
}</code></pre>
</div>
@@ -533,7 +534,7 @@ the default Feign native annotations.
</div>
</div>
<div class="sect2">
<h3 id="spring-cloud-feign-hystrix"><a class="link" href="#spring-cloud-feign-hystrix">Feign Hystrix Support</a></h3>
<h3 id="spring-cloud-feign-hystrix"><a class="anchor" href="#spring-cloud-feign-hystrix"></a><a class="link" href="#spring-cloud-feign-hystrix">1.4. Feign Hystrix Support</a></h3>
<div class="paragraph">
<p>If Hystrix is on the classpath and <code>feign.hystrix.enabled=true</code>, Feign will wrap all methods with a circuit breaker. Returning a <code>com.netflix.hystrix.HystrixCommand</code> is also available. This lets you use reactive patterns (with a call to <code>.toObservable()</code> or <code>.observe()</code> or asynchronous use (with a call to <code>.queue()</code>).</p>
</div>
@@ -544,11 +545,11 @@ the default Feign native annotations.
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Configuration
public class FooConfiguration {
@Bean
@Scope("prototype")
public Feign.Builder feignBuilder() {
return Feign.builder();
}
@Bean
@Scope("prototype")
public Feign.Builder feignBuilder() {
return Feign.builder();
}
}</code></pre>
</div>
</div>
@@ -568,7 +569,7 @@ favor for an opt-in approach.
</div>
</div>
<div class="sect2">
<h3 id="spring-cloud-feign-hystrix-fallback"><a class="link" href="#spring-cloud-feign-hystrix-fallback">Feign Hystrix Fallbacks</a></h3>
<h3 id="spring-cloud-feign-hystrix-fallback"><a class="anchor" href="#spring-cloud-feign-hystrix-fallback"></a><a class="link" href="#spring-cloud-feign-hystrix-fallback">1.5. Feign Hystrix Fallbacks</a></h3>
<div class="paragraph">
<p>Hystrix supports the notion of a fallback: a default code path that is executed when they circuit is open or there is an error. To enable fallbacks for a given <code>@FeignClient</code> set the <code>fallback</code> attribute to the class name that implements the fallback. You also need to declare your implementation as a Spring bean.</p>
</div>
@@ -595,21 +596,21 @@ static class HystrixClientFallback implements HystrixClient {
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@FeignClient(name = "hello", fallbackFactory = HystrixClientFallbackFactory.class)
protected interface HystrixClient {
@RequestMapping(method = RequestMethod.GET, value = "/hello")
Hello iFailSometimes();
@RequestMapping(method = RequestMethod.GET, value = "/hello")
Hello iFailSometimes();
}
@Component
static class HystrixClientFallbackFactory implements FallbackFactory&lt;HystrixClient&gt; {
@Override
public HystrixClient create(Throwable cause) {
return new HystrixClient() {
@Override
public Hello iFailSometimes() {
return new Hello("fallback; reason was: " + cause.getMessage());
}
};
}
@Override
public HystrixClient create(Throwable cause) {
return new HystrixClient() {
@Override
public Hello iFailSometimes() {
return new Hello("fallback; reason was: " + cause.getMessage());
}
};
}
}</code></pre>
</div>
</div>
@@ -627,7 +628,7 @@ There is a limitation with the implementation of fallbacks in Feign and how Hyst
</div>
</div>
<div class="sect2">
<h3 id="_feign_and_primary"><a class="link" href="#_feign_and_primary">Feign and <code>@Primary</code></a></h3>
<h3 id="feign-and-primary"><a class="anchor" href="#feign-and-primary"></a><a class="link" href="#feign-and-primary">1.6. Feign and <code>@Primary</code></a></h3>
<div class="paragraph">
<p>When using Feign with Hystrix fallbacks, there are multiple beans in the <code>ApplicationContext</code> of the same type. This will cause <code>@Autowired</code> to not work because there isn&#8217;t exactly one bean, or one marked as primary. To work around this, Spring Cloud Netflix marks all Feign instances as <code>@Primary</code>, so Spring Framework will know which bean to inject. In some cases, this may not be desirable. To turn off this behavior set the <code>primary</code> attribute of <code>@FeignClient</code> to false.</p>
</div>
@@ -635,13 +636,13 @@ There is a limitation with the implementation of fallbacks in Feign and how Hyst
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@FeignClient(name = "hello", primary = false)
public interface HelloClient {
// methods here
// methods here
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="spring-cloud-feign-inheritance"><a class="link" href="#spring-cloud-feign-inheritance">Feign Inheritance Support</a></h3>
<h3 id="spring-cloud-feign-inheritance"><a class="anchor" href="#spring-cloud-feign-inheritance"></a><a class="link" href="#spring-cloud-feign-inheritance">1.7. Feign Inheritance Support</a></h3>
<div class="paragraph">
<p>Feign supports boilerplate apis via single-inheritance interfaces.
This allows grouping common operations into convenient base interfaces.</p>
@@ -693,7 +694,7 @@ mapping is not inherited).
</div>
</div>
<div class="sect2">
<h3 id="_feign_requestresponse_compression"><a class="link" href="#_feign_requestresponse_compression">Feign request/response compression</a></h3>
<h3 id="feign-requestresponse-compression"><a class="anchor" href="#feign-requestresponse-compression"></a><a class="link" href="#feign-requestresponse-compression">1.8. Feign request/response compression</a></h3>
<div class="paragraph">
<p>You may consider enabling the request or response GZIP compression for your
Feign requests. You can do this by enabling one of the properties:</p>
@@ -719,7 +720,7 @@ feign.compression.request.min-request-size=2048</code></pre>
</div>
</div>
<div class="sect2">
<h3 id="_feign_logging"><a class="link" href="#_feign_logging">Feign logging</a></h3>
<h3 id="feign-logging"><a class="anchor" href="#feign-logging"></a><a class="link" href="#feign-logging">1.9. Feign logging</a></h3>
<div class="paragraph">
<p>A logger is created for each Feign client created. By default the name of the logger is the full class name of the interface used to create the Feign client. Feign logging only responds to the <code>DEBUG</code> level.</p>
</div>
@@ -764,7 +765,7 @@ public class FooConfiguration {
</div>
</div>
<div class="sect2">
<h3 id="_feign_querymap_support"><a class="link" href="#_feign_querymap_support">Feign @QueryMap support</a></h3>
<h3 id="feign-querymap-support"><a class="anchor" href="#feign-querymap-support"></a><a class="link" href="#feign-querymap-support">1.10. Feign @QueryMap support</a></h3>
<div class="paragraph">
<p>The OpenFeign <code>@QueryMap</code> annotation provides support for POJOs to be used as
GET parameter maps. Unfortunately, the default OpenFeign QueryMap annotation is
@@ -806,7 +807,7 @@ public interface DemoTemplate {
</div>
</div>
<div class="sect2">
<h3 id="_hateoas_support"><a class="link" href="#_hateoas_support">HATEOAS support</a></h3>
<h3 id="hateoas-support"><a class="anchor" href="#hateoas-support"></a><a class="link" href="#hateoas-support">1.11. HATEOAS support</a></h3>
<div class="paragraph">
<p>Spring provides some APIs to create REST representations that follow the <a href="https://en.wikipedia.org/wiki/HATEOAS">HATEOAS</a> principle, <a href="https://spring.io/projects/spring-hateoas">Spring Hateoas</a> and <a href="https://spring.io/projects/spring-data-rest">Spring Data REST</a>.</p>
</div>
@@ -831,6 +832,14 @@ public interface DemoTemplate {
</div>
</div>
</div>
<div class="sect1">
<h2 id="configuration-properties"><a class="anchor" href="#configuration-properties"></a><a class="link" href="#configuration-properties">2. Configuration properties</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>To see the list of all Sleuth related configuration properties please check <a href="appendix.html">the Appendix page</a>.</p>
</div>
</div>
</div>
</div>
<script type="text/javascript" src="js/tocbot/tocbot.min.js"></script>
<script type="text/javascript" src="js/toc.js"></script>