Skip to content

Commit 546ff97

Browse files
committed
update docs
1 parent 3ec5fe9 commit 546ff97

File tree

3 files changed

+75
-48
lines changed

3 files changed

+75
-48
lines changed

README.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,23 @@ public interface PostApi {
153153
}
154154
```
155155

156+
### Dynamic Refresh Configuration
157+
158+
Support to dynamically refresh the configuration of clients, you can put the configuration in the configuration
159+
center ([Consul](https://github.com/hashicorp/consul), [Apollo](https://github.com/apolloconfig/apollo), [Nacos](https://github.com/alibaba/nacos),
160+
etc.), and change the configuration (e.g. `base-url`, `timeout`, `headers`), the client will be refreshed automatically
161+
without restarting the application.
162+
163+
Use following configuration to enable this feature:
164+
165+
```yaml
166+
http-exchange:
167+
refresh:
168+
enabled: true # default is false
169+
```
170+
171+
> This feature needs `spring-cloud-context` in the classpath and a `RefreshEvent` was published.
172+
156173
### Configuration Driven
157174

158175
Providing a lot of configuration properties to customize the behavior of the client.
@@ -166,6 +183,8 @@ http-exchange:
166183
headers: # global headers
167184
- key: X-App-Name
168185
values: ${spring.application.name}
186+
refresh:
187+
enabled: true # enable dynamic refresh configuration
169188
channels:
170189
- base-url: http://order # client specific base-url, will override global base-url
171190
response-timeout: 1000 # client specific timeout, will override global timeout

docs/README.md

Lines changed: 54 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
### Introduction
1+
## Introduction
22

3-
`httpexchange-spring-boot-starter` is the missing starter for Spring 6.x declarative HTTP client.
3+
`httpexchange-spring-boot-starter` is the missing starter for Spring 6.x declarative HTTP client.
44

5-
Spring 6.0 has provided its native support for declarative HTTP clients, you don't need to
5+
Spring 6.x has provided its native support for declarative HTTP clients, you don't need to
66
use [Spring Cloud OpenFeign](https://github.com/spring-cloud/spring-cloud-openfeign)
77
or [Spring Cloud Square](https://github.com/spring-projects-experimental/spring-cloud-square) anymore.
88
See [Spring Documentation](https://docs.spring.io/spring-framework/docs/6.0.0/reference/html/integration.html#rest-http-interface)
@@ -60,36 +60,23 @@ _**So what is the problem ? 🤔**_
6060
Native support for declarative HTTP clients is great, but it introduces a whole new set of annotations, such as
6161
`@GetExchange`, `@PostExchange`, etc. And does not support Spring web annotations, such as
6262
`@GetMapping`, `@PostMapping`, etc, which is extremely painful for users that using `Spring Cloud OpenFeign` and want
63-
to migrate to Spring 6.0.
63+
to migrate to Spring 6.x.
6464

65-
**The main goal of this project is providing a `Spring Cloud OpenFeign` like experience for Spring 6.0 declarative HTTP
65+
**The main goal of this project is providing a `Spring Cloud OpenFeign` like experience for Spring 6.x declarative HTTP
6666
clients and support Spring web annotations (`@GetMapping`, `@PostMapping`).**
6767

68-
### Quick Start
68+
## Quick Start
6969

7070
Add dependency:
7171

72-
<!-- tabs:start -->
73-
74-
#### ** Gradle **
75-
76-
```groovy
77-
implementation 'com.freemanan:httpexchange-spring-boot-starter:3.1.1'
78-
```
79-
80-
#### ** Maven **
81-
8272
```xml
83-
8473
<dependency>
8574
<groupId>com.freemanan</groupId>
8675
<artifactId>httpexchange-spring-boot-starter</artifactId>
8776
<version>3.1.1</version>
8877
</dependency>
8978
```
9079

91-
<!-- tabs:end -->
92-
9380
Write a classic Spring Boot application:
9481

9582
```java
@@ -113,9 +100,9 @@ interface PostApi {
113100

114101
> No more boilerplate code! 🎉
115102
116-
### Features
103+
## Features
117104

118-
#### Autoconfigure Clients
105+
### Autoconfigure Clients
119106

120107
Autoconfigure clients, all you need to do is adding the `@EnableExchangeClients` annotation. `@EnableExchangeClients` is
121108
very similar to `@EnableFeignClients`.
@@ -145,7 +132,7 @@ You can also specify the clients and the packages to scan at the same time.
145132

146133
> `Spring Cloud OpenFeign` does not support using `basePackages` and `clients` at the same time.
147134
148-
#### Spring Web Annotations Support
135+
### Spring Web Annotations Support
149136

150137
Support to use spring web annotations to generate HTTP client, e.g. `@RequestMapping`, `@GetMapping`, `@PostMapping`
151138
etc.
@@ -158,34 +145,53 @@ public interface PostApi {
158145
}
159146
```
160147

161-
#### Configuration Driven
148+
### Dynamic Refresh Configuration
149+
150+
Support to dynamically refresh the configuration of clients, you can put the configuration in the configuration
151+
center ([Consul](https://github.com/hashicorp/consul), [Apollo](https://github.com/apolloconfig/apollo), [Nacos](https://github.com/alibaba/nacos),
152+
etc.), and change the configuration (e.g. `base-url`, `timeout`, `headers`), the client will be refreshed automatically
153+
without restarting the application.
154+
155+
Use following configuration to enable this feature:
156+
157+
```yaml
158+
http-exchange:
159+
refresh:
160+
enabled: true # default is false
161+
```
162+
163+
> This feature needs `spring-cloud-context` in the classpath and a `RefreshEvent` was published.
164+
165+
### Configuration Driven
162166

163167
Providing a lot of configuration properties to customize the behavior of the client.
164168

165169
You can configure the `base-url`, `timeout` and `headers` for each channel, and each channel can apply to multiple clients.
166170

167171
```yaml
168172
http-exchange:
169-
base-url: http://api-gateway # global base-url
170-
response-timeout: 10000 # global timeout
171-
headers: # global headers
172-
- key: X-App-Name
173-
values: ${spring.application.name}
174-
channels:
175-
- base-url: http://order # client specific base-url, will override global base-url
176-
response-timeout: 1000 # client specific timeout, will override global timeout
177-
headers: # client specific headers, will merge with global headers
178-
- key: X-Key
179-
values: [value1, value2]
180-
clients: # client to apply this channel
181-
- OrderApi
182-
- base-url: user
183-
response-timeout: 2000
184-
clients:
185-
- UserApi
186-
- com.example.**.api.* # Ant-style pattern
187-
- base-url: service-foo.namespace
188-
classes: [com.example.FooApi] # client class to apply this channel
173+
base-url: http://api-gateway # global base-url
174+
response-timeout: 10000 # global timeout
175+
headers: # global headers
176+
- key: X-App-Name
177+
values: ${spring.application.name}
178+
refresh:
179+
enabled: true # enable dynamic refresh configuration
180+
channels:
181+
- base-url: http://order # client specific base-url, will override global base-url
182+
response-timeout: 1000 # client specific timeout, will override global timeout
183+
headers: # client specific headers, will merge with global headers
184+
- key: X-Key
185+
values: [value1, value2]
186+
clients: # client to apply this channel
187+
- OrderApi
188+
- base-url: user
189+
response-timeout: 2000
190+
clients:
191+
- UserApi
192+
- com.example.**.api.* # Ant-style pattern
193+
- base-url: service-foo.namespace
194+
classes: [com.example.FooApi] # client class to apply this channel
189195
```
190196

191197
Using property `clients` or `classes` to identify the client, use `classes` first if configured, otherwise use `clients`.
@@ -205,7 +211,7 @@ http-exchange:
205211

206212
> configuration `clients` is more flexible, it supports Ant-style pattern, `classes` is more IDE-friendly and efficient.
207213

208-
#### Url Variables
214+
### Url Variables
209215

210216
```java
211217
@HttpExchange("${api.post.url}")
@@ -215,7 +221,7 @@ public interface PostApi {
215221
}
216222
```
217223

218-
#### Validation
224+
### Validation
219225

220226
```java
221227
@HttpExchange("${api.post.url}")
@@ -230,7 +236,7 @@ public interface PostApi {
230236
> see [issue](https://github.com/spring-projects/spring-framework/issues/29782)
231237
> and [tests](src/test/java/com/freemanan/starter/httpexchange/ValidationTests.java)
232238

233-
#### Convert Java Bean to Query
239+
### Convert Java Bean to Query
234240

235241
In Spring Web/WebFlux (server side), it will automatically convert query string to Java Bean,
236242
but `Spring Cloud OpenFeign` or `Exchange client of Spring 6` does not support to convert Java bean to query string by
@@ -252,7 +258,7 @@ Auto convert **non-null simple values** fields of `condition` to query string.
252258

253259
> Simple values: primitive/wrapper types, String, Date, etc.
254260

255-
#### Customize Resolvers
261+
### Customize Resolvers
256262

257263
```java
258264
@Bean
@@ -270,7 +276,7 @@ Auto-detect all of the `HttpServiceArgumentResolver` beans and `StringValueResol
270276
the `HttpServiceProxyFactory`.
271277

272278

273-
### Version
279+
## Version
274280

275281
This project should work with any version of Spring Boot 3.
276282

src/main/resources/application-http-exchange-statrer-example.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ http-exchange:
55
headers:
66
- key: X-App-Name
77
values: ${spring.application.name}
8+
refresh:
9+
enabled: true
810
channels:
911
- base-url: http://order
1012
response-timeout: 1000

0 commit comments

Comments
 (0)