From 9f5e5ed959034e80687c5f148fcceffa10080621 Mon Sep 17 00:00:00 2001 From: Olga MaciaszekSharma Date: Fri, 15 Sep 2023 18:10:24 +0200 Subject: [PATCH 01/10] Migrate Structure --- docs/{src/main/asciidoc => modules/ROOT/pages}/README.adoc | 0 docs/{src/main/asciidoc => modules/ROOT/pages}/_attributes.adoc | 0 docs/{src/main/asciidoc => modules/ROOT/pages}/_configprops.adoc | 0 docs/{src/main/asciidoc => modules/ROOT/pages}/appendix.adoc | 0 docs/{src/main/asciidoc => modules/ROOT/pages}/index.adoc | 0 docs/{src/main/asciidoc => modules/ROOT/pages}/intro.adoc | 0 docs/{src/main/asciidoc => modules/ROOT/pages}/sagan-boot.adoc | 0 docs/{src/main/asciidoc => modules/ROOT/pages}/sagan-index.adoc | 0 .../asciidoc => modules/ROOT/pages}/spring-cloud-openfeign.adoc | 0 9 files changed, 0 insertions(+), 0 deletions(-) rename docs/{src/main/asciidoc => modules/ROOT/pages}/README.adoc (100%) rename docs/{src/main/asciidoc => modules/ROOT/pages}/_attributes.adoc (100%) rename docs/{src/main/asciidoc => modules/ROOT/pages}/_configprops.adoc (100%) rename docs/{src/main/asciidoc => modules/ROOT/pages}/appendix.adoc (100%) rename docs/{src/main/asciidoc => modules/ROOT/pages}/index.adoc (100%) rename docs/{src/main/asciidoc => modules/ROOT/pages}/intro.adoc (100%) rename docs/{src/main/asciidoc => modules/ROOT/pages}/sagan-boot.adoc (100%) rename docs/{src/main/asciidoc => modules/ROOT/pages}/sagan-index.adoc (100%) rename docs/{src/main/asciidoc => modules/ROOT/pages}/spring-cloud-openfeign.adoc (100%) diff --git a/docs/src/main/asciidoc/README.adoc b/docs/modules/ROOT/pages/README.adoc similarity index 100% rename from docs/src/main/asciidoc/README.adoc rename to docs/modules/ROOT/pages/README.adoc diff --git a/docs/src/main/asciidoc/_attributes.adoc b/docs/modules/ROOT/pages/_attributes.adoc similarity index 100% rename from docs/src/main/asciidoc/_attributes.adoc rename to docs/modules/ROOT/pages/_attributes.adoc diff --git a/docs/src/main/asciidoc/_configprops.adoc b/docs/modules/ROOT/pages/_configprops.adoc similarity index 100% rename from docs/src/main/asciidoc/_configprops.adoc rename to docs/modules/ROOT/pages/_configprops.adoc diff --git a/docs/src/main/asciidoc/appendix.adoc b/docs/modules/ROOT/pages/appendix.adoc similarity index 100% rename from docs/src/main/asciidoc/appendix.adoc rename to docs/modules/ROOT/pages/appendix.adoc diff --git a/docs/src/main/asciidoc/index.adoc b/docs/modules/ROOT/pages/index.adoc similarity index 100% rename from docs/src/main/asciidoc/index.adoc rename to docs/modules/ROOT/pages/index.adoc diff --git a/docs/src/main/asciidoc/intro.adoc b/docs/modules/ROOT/pages/intro.adoc similarity index 100% rename from docs/src/main/asciidoc/intro.adoc rename to docs/modules/ROOT/pages/intro.adoc diff --git a/docs/src/main/asciidoc/sagan-boot.adoc b/docs/modules/ROOT/pages/sagan-boot.adoc similarity index 100% rename from docs/src/main/asciidoc/sagan-boot.adoc rename to docs/modules/ROOT/pages/sagan-boot.adoc diff --git a/docs/src/main/asciidoc/sagan-index.adoc b/docs/modules/ROOT/pages/sagan-index.adoc similarity index 100% rename from docs/src/main/asciidoc/sagan-index.adoc rename to docs/modules/ROOT/pages/sagan-index.adoc diff --git a/docs/src/main/asciidoc/spring-cloud-openfeign.adoc b/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc similarity index 100% rename from docs/src/main/asciidoc/spring-cloud-openfeign.adoc rename to docs/modules/ROOT/pages/spring-cloud-openfeign.adoc From 1e7f3285867aeed67bc687221ad9d4343a1aa2c8 Mon Sep 17 00:00:00 2001 From: Olga MaciaszekSharma Date: Fri, 15 Sep 2023 18:10:24 +0200 Subject: [PATCH 02/10] Insert explicit ids for headers --- docs/modules/ROOT/pages/README.adoc | 4 ++++ .../ROOT/pages/spring-cloud-openfeign.adoc | 23 +++++++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/docs/modules/ROOT/pages/README.adoc b/docs/modules/ROOT/pages/README.adoc index 2af86f623..5a56ee11f 100644 --- a/docs/modules/ROOT/pages/README.adoc +++ b/docs/modules/ROOT/pages/README.adoc @@ -8,18 +8,22 @@ include::_attributes.adoc[] include::intro.adoc[] +[[features]] == Features * Declarative REST Client: Feign creates a dynamic implementation of an interface decorated with JAX-RS or Spring MVC annotations +[[building]] == Building include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/docs/src/main/asciidoc/building-jdk8.adoc[] +[[contributing]] == Contributing include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/docs/src/main/asciidoc/contributing.adoc[] +[[license]] == License The project license file is available https://raw.githubusercontent.com/spring-cloud/spring-cloud-openfeign/main/LICENSE.txt[here]. diff --git a/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc b/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc index fef52d128..50b765f5b 100644 --- a/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc +++ b/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc @@ -1,3 +1,4 @@ +[[spring-cloud-openfeign]] = Spring Cloud OpenFeign include::_attributes.adoc[] @@ -290,6 +291,7 @@ public FeignClientConfigurer feignClientConfigurer() { TIP: By default, Feign clients do not encode slash `/` characters. You can change this behaviour, by setting the value of `spring.cloud.openfeign.client.decodeSlash` to `false`. +[[springencoder-configuration]] ==== `SpringEncoder` configuration In the `SpringEncoder` that we provide, we set `null` charset for binary content types and `UTF-8` for all the other ones. @@ -306,6 +308,7 @@ We can configure timeouts on both the default and the named client. OpenFeign wo NOTE: In case the server is not running or available a packet results in _connection refused_. The communication ends either with an error message or in a fallback. This can happen _before_ the `connectTimeout` if it is set very low. The time taken to perform a lookup and to receive such a packet causes a significant part of this delay. It is subject to change based on the remote host that involves a DNS lookup. +[[creating-feign-clients-manually]] === Creating Feign Clients Manually In some cases it might be necessary to customize your Feign Clients in a way that is not @@ -511,6 +514,7 @@ If one needs access to the cause that made the fallback trigger, one can use the } ---- +[[feign-and-primary]] === Feign and `@Primary` When using Feign with Spring Cloud CircuitBreaker fallbacks, there are multiple beans in the `ApplicationContext` of the same type. This will cause `@Autowired` to not work because there isn't exactly one bean, or one marked as primary. To work around this, Spring Cloud OpenFeign marks all Feign instances as `@Primary`, so Spring Framework will know which bean to inject. In some cases, this may not be desirable. To turn off this behavior set the `primary` attribute of `@FeignClient` to false. @@ -561,6 +565,7 @@ public interface UserClient extends UserService { WARNING: `@FeignClient` interfaces should not be shared between server and client and annotating `@FeignClient` interfaces with `@RequestMapping` on class level is no longer supported. +[[feign-request/response-compression]] === Feign request/response compression You may consider enabling the request or response GZIP compression for your @@ -585,6 +590,7 @@ These properties allow you to be selective about the compressed media types and TIP: Since the OkHttpClient uses "transparent" compression, that is disabled if the `content-encoding` or `accept-encoding` header is present, we do not enable compression when `feign.okhttp.OkHttpClient` is present on the classpath and `spring.cloud.openfeign.okhttp.enabled` is set to `true`. +[[feign-logging]] === Feign logging 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 `DEBUG` level. @@ -616,6 +622,7 @@ public class FooConfiguration { } ---- +[[feign-capability-support]] === Feign Capability support The Feign capabilities expose core Feign components so that these components can be modified. For example, the capabilities can take the `Client`, _decorate_ it, and give the decorated instance back to Feign. @@ -634,6 +641,7 @@ public class FooConfiguration { } ---- +[[micrometer-support]] === Micrometer Support If all of the following conditions are true, a `MicrometerObservationCapability` bean is created and registered so that your Feign client is observable by Micrometer: @@ -682,6 +690,7 @@ public class FooConfiguration { } ---- +[[feign-caching]] === Feign Caching If `@EnableCaching` annotation is used, a `CachingCapability` bean is created and registered so that your Feign client recognizes `@Cache*` annotations on its interface: @@ -698,6 +707,7 @@ public interface DemoClient { You can also disable the feature via property `spring.cloud.openfeign.cache.enabled=false`. +[[feign-querymap-support]] === Feign @QueryMap support Spring Cloud OpenFeign provides an equivalent `@SpringQueryMap` annotation, which @@ -730,6 +740,7 @@ public interface DemoTemplate { If you need more control over the generated query parameter map, you can implement a custom `QueryMapEncoder` bean. +[[hateoas-support]] === HATEOAS support Spring provides some APIs to create REST representations that follow the https://en.wikipedia.org/wiki/HATEOAS[HATEOAS] principle, https://spring.io/projects/spring-hateoas[Spring Hateoas] and https://spring.io/projects/spring-data-rest[Spring Data REST]. @@ -750,6 +761,7 @@ public interface DemoTemplate { } ---- +[[spring-matrixvariable-support]] === Spring @MatrixVariable Support Spring Cloud OpenFeign provides support for the Spring `@MatrixVariable` annotation. @@ -780,6 +792,7 @@ public interface DemoTemplate { } ---- +[[feign-collectionformat-support]] === Feign `CollectionFormat` support We support `feign.CollectionFormat` by providing the `@CollectionFormat` annotation. You can annotate a Feign client method (or the whole class to affect all methods) with it by passing the desired `feign.CollectionFormat` as annotation value. @@ -798,11 +811,13 @@ protected interface DemoFeignClient { } ---- +[[reactive-support]] === Reactive Support As the https://github.com/OpenFeign/feign[OpenFeign project] does not currently support reactive clients, such as https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/reactive/function/client/WebClient.html[Spring WebClient], neither does Spring Cloud OpenFeign.We will add support for it here as soon as it becomes available in the core project. Until that is done, we recommend using https://github.com/Playtika/feign-reactive[feign-reactive] for Spring WebClient support. +[[early-initialization-errors]] ==== Early Initialization Errors Depending on how you are using your Feign clients you may see initialization errors when starting your application. @@ -814,6 +829,7 @@ To work around this problem you can use an `ObjectProvider` when autowiring your ObjectProvider testFeignClient; ---- +[[spring-data-support]] === Spring Data Support If Jackson Databind and Spring Data Commons are on the classpath, converters for `org.springframework.data.domain.Page` and `org.springframework.data.domain.Sort` will be added automatically. @@ -826,6 +842,7 @@ spring.cloud.openfeign.autoconfiguration.jackson.enabled=false See `org.springframework.cloud.openfeign.FeignAutoConfiguration.FeignJacksonConfiguration` for details. +[[spring-refreshscope-support]] === Spring `@RefreshScope` Support If Feign client refresh is enabled, each Feign client is created with: @@ -842,6 +859,7 @@ spring.cloud.openfeign.client.refresh-enabled=true ---- TIP: DO NOT annotate the `@FeignClient` interface with the `@RefreshScope` annotation. +[[oauth2-support]] === OAuth2 Support OAuth2 support can be enabled by setting following flag: ---- @@ -854,6 +872,7 @@ TIP:: Using the `serviceId` as OAuth2 client registrationId is convenient for lo TIP:: If you do not want to use the default setup for the `OAuth2AuthorizedClientManager`, you can just instantiate a bean of this type in your configuration. +[[transform-the-load-balanced-http-request]] === Transform the load-balanced HTTP request You can use the selected `ServiceInstance` to transform the load-balanced HTTP Request. @@ -881,6 +900,7 @@ For `Request`, you need to implement and define `LoadBalancerFeignRequestTransfo If multiple transformers are defined, they are applied in the order in which beans are defined. Alternatively, you can use `LoadBalancerFeignRequestTransformer.DEFAULT_ORDER` to specify the order. +[[x-forwarded-headers-support]] === X-Forwarded Headers Support `X-Forwarded-Host` and `X-Forwarded-Proto` support can be enabled by setting following flag: @@ -890,6 +910,7 @@ Alternatively, you can use `LoadBalancerFeignRequestTransformer.DEFAULT_ORDER` t spring.cloud.loadbalancer.x-forwarded.enabled=true ---- +[[supported-ways-to-provide-url-to-a-feign-client]] === Supported Ways To Provide URL To A Feign Client You can provide a URL to a Feign client in any of the following ways: @@ -919,6 +940,7 @@ The URL provided in the configuration properties remains unused. |=== +[[aot-and-native-image-support]] === AOT and Native Image Support Spring Cloud OpenFeign supports Spring AOT transformations and native images, however, only with refresh mode disabled, Feign clients refresh disabled (default setting) and <> disabled (default setting). @@ -931,6 +953,7 @@ TIP: If you want to run Spring Cloud OpenFeign clients in AOT or native image mo TIP: However, if you set the `url` value via properties, it is possible to override the `@FeignClient` `url` value by running the image with `-Dspring.cloud.openfeign.client.config.[clientId].url=[url]` flag. In order to enable overriding, a `url` value also has to be set via properties and not `@FeignClient` attribute during buildtime. +[[configuration-properties]] == Configuration properties To see the list of all Spring Cloud OpenFeign related configuration properties please check link:appendix.html[the Appendix page]. From 78db37fb3731bd4c46cced66de26e5230c907c65 Mon Sep 17 00:00:00 2001 From: Olga MaciaszekSharma Date: Fri, 15 Sep 2023 18:10:24 +0200 Subject: [PATCH 03/10] Remove unnecessary asciidoc attributes --- docs/modules/ROOT/pages/_attributes.adoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/modules/ROOT/pages/_attributes.adoc b/docs/modules/ROOT/pages/_attributes.adoc index 6efc1231d..a42e7dea7 100644 --- a/docs/modules/ROOT/pages/_attributes.adoc +++ b/docs/modules/ROOT/pages/_attributes.adoc @@ -1,8 +1,6 @@ :doctype: book :idprefix: :idseparator: - -:toc: left -:toclevels: 4 :tabsize: 4 :numbered: :sectanchors: From 470f6b2f213ba81a371a4d89954be92bc4e25fb0 Mon Sep 17 00:00:00 2001 From: Olga MaciaszekSharma Date: Fri, 15 Sep 2023 18:10:24 +0200 Subject: [PATCH 04/10] Copy default antora files --- docs/.github/workflows/deploy-docs.yml | 32 +++++++++++++++++++ docs/antora-playbook.yml | 43 ++++++++++++++++++++++++++ docs/antora.yml | 12 +++++++ 3 files changed, 87 insertions(+) create mode 100644 docs/.github/workflows/deploy-docs.yml create mode 100644 docs/antora-playbook.yml create mode 100644 docs/antora.yml diff --git a/docs/.github/workflows/deploy-docs.yml b/docs/.github/workflows/deploy-docs.yml new file mode 100644 index 000000000..be4b92dfc --- /dev/null +++ b/docs/.github/workflows/deploy-docs.yml @@ -0,0 +1,32 @@ +name: Deploy Docs +on: + push: + branches-ignore: [ gh-pages ] + tags: '**' + repository_dispatch: + types: request-build-reference # legacy + #schedule: + #- cron: '0 10 * * *' # Once per day at 10am UTC + workflow_dispatch: +permissions: + actions: write +jobs: + build: + runs-on: ubuntu-latest + # if: github.repository_owner == 'spring-cloud' + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + ref: docs-build + fetch-depth: 1 + - name: Dispatch (partial build) + if: github.ref_type == 'branch' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }} + - name: Dispatch (full build) + if: github.ref_type == 'tag' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) diff --git a/docs/antora-playbook.yml b/docs/antora-playbook.yml new file mode 100644 index 000000000..9a70e676c --- /dev/null +++ b/docs/antora-playbook.yml @@ -0,0 +1,43 @@ +antora: + extensions: + - '@springio/antora-extensions/partial-build-extension' + - require: '@springio/antora-extensions/latest-version-extension' + - require: '@springio/antora-extensions/inject-collector-cache-config-extension' + - '@antora/collector-extension' + - '@antora/atlas-extension' + - require: '@springio/antora-extensions/root-component-extension' + root_component_name: 'PROJECT_WITHOUT_SPRING' + # FIXME: Run antora once using this extension to migrate to the Asciidoc Tabs syntax + # and then remove this extension + - require: '@springio/antora-extensions/tabs-migration-extension' + unwrap_example_block: always + save_result: true +site: + title: PROJECT_FULL_NAME + url: https://docs.spring.io/PROJECT_NAME/reference/ +content: + sources: + - url: ./.. + branches: HEAD + start_path: docs + worktrees: true +asciidoc: + attributes: + page-stackoverflow-url: https://stackoverflow.com/tags/spring-cloud + page-pagination: '' + hide-uri-scheme: '@' + tabs-sync-option: '@' + chomp: 'all' + extensions: + - '@asciidoctor/tabs' + - '@springio/asciidoctor-extensions' + sourcemap: true +urls: + latest_version_segment: '' +runtime: + log: + failure_level: warn + format: pretty +ui: + bundle: + url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.5/ui-bundle.zip diff --git a/docs/antora.yml b/docs/antora.yml new file mode 100644 index 000000000..15b346da0 --- /dev/null +++ b/docs/antora.yml @@ -0,0 +1,12 @@ +name: PROJECT_WITHOUT_SPRING +version: true +title: PROJECT_NAME +nav: + - modules/ROOT/nav.adoc +ext: + collector: + run: + command: ./mvnw --no-transfer-progress -B process-resources -Pdocs -pl docs -Dantora-maven-plugin.phase=none -Dgenerate-docs.phase=none -Dgenerate-readme.phase=none -Dgenerate-cloud-resources.phase=none -Dmaven-dependency-plugin-for-docs.phase=none -Dmaven-dependency-plugin-for-docs-classes.phase=none -DskipTests + local: true + scan: + dir: ./target/classes/antora-resources/ From 9c8d2812d9f752ef0009329487c1763a7c7420f0 Mon Sep 17 00:00:00 2001 From: Olga MaciaszekSharma Date: Fri, 15 Sep 2023 18:10:24 +0200 Subject: [PATCH 05/10] Fix indentation for all pages --- docs/modules/ROOT/pages/README.adoc | 8 ++++---- docs/modules/ROOT/pages/appendix.adoc | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/modules/ROOT/pages/README.adoc b/docs/modules/ROOT/pages/README.adoc index 5a56ee11f..da748822b 100644 --- a/docs/modules/ROOT/pages/README.adoc +++ b/docs/modules/ROOT/pages/README.adoc @@ -9,21 +9,21 @@ include::_attributes.adoc[] include::intro.adoc[] [[features]] -== Features += Features * Declarative REST Client: Feign creates a dynamic implementation of an interface decorated with JAX-RS or Spring MVC annotations [[building]] -== Building += Building include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/docs/src/main/asciidoc/building-jdk8.adoc[] [[contributing]] -== Contributing += Contributing include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/docs/src/main/asciidoc/contributing.adoc[] [[license]] -== License += License The project license file is available https://raw.githubusercontent.com/spring-cloud/spring-cloud-openfeign/main/LICENSE.txt[here]. diff --git a/docs/modules/ROOT/pages/appendix.adoc b/docs/modules/ROOT/pages/appendix.adoc index 39eb1593e..941e773b2 100644 --- a/docs/modules/ROOT/pages/appendix.adoc +++ b/docs/modules/ROOT/pages/appendix.adoc @@ -1,7 +1,7 @@ :numbered!: [appendix] [[common-application-properties]] -== Common application properties += Common application properties include::_attributes.adoc[] From 01c8b817f8bc491fdc04d1de387f6ba1b1292c4e Mon Sep 17 00:00:00 2001 From: Olga MaciaszekSharma Date: Fri, 15 Sep 2023 18:10:24 +0200 Subject: [PATCH 06/10] Generate a default navigation --- docs/modules/ROOT/nav.adoc | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 docs/modules/ROOT/nav.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc new file mode 100644 index 000000000..5d5a53a8b --- /dev/null +++ b/docs/modules/ROOT/nav.adoc @@ -0,0 +1,9 @@ +* xref:index.adoc[] +* xref:spring-cloud-openfeign.adoc[] +* xref:_attributes.adoc[] +* xref:intro.adoc[] +* xref:README.adoc[] +* xref:_configprops.adoc[] +* xref:appendix.adoc[] +* xref:sagan-boot.adoc[] +* xref:sagan-index.adoc[] From 3e19002672b674d9ce491dcf7a0ef792c9f0b698 Mon Sep 17 00:00:00 2001 From: Olga MaciaszekSharma Date: Fri, 15 Sep 2023 18:10:24 +0200 Subject: [PATCH 07/10] Remove includes --- docs/modules/ROOT/pages/README.adoc | 2 -- docs/modules/ROOT/pages/appendix.adoc | 2 -- docs/modules/ROOT/pages/index.adoc | 1 - docs/modules/ROOT/pages/spring-cloud-openfeign.adoc | 2 -- 4 files changed, 7 deletions(-) diff --git a/docs/modules/ROOT/pages/README.adoc b/docs/modules/ROOT/pages/README.adoc index da748822b..ccfa990a1 100644 --- a/docs/modules/ROOT/pages/README.adoc +++ b/docs/modules/ROOT/pages/README.adoc @@ -4,9 +4,7 @@ image:https://codecov.io/gh/spring-cloud/spring-cloud-openfeign/branch/main/grap image:https://api.codacy.com/project/badge/Grade/97b04c4e609c4b4f86b415e4437a6484["Codacy code quality", link="https://www.codacy.com/app/Spring-Cloud/spring-cloud-openfeign?utm_source=github.com&utm_medium=referral&utm_content=spring-cloud/spring-cloud-openfeign&utm_campaign=Badge_Grade"] -include::_attributes.adoc[] -include::intro.adoc[] [[features]] = Features diff --git a/docs/modules/ROOT/pages/appendix.adoc b/docs/modules/ROOT/pages/appendix.adoc index 941e773b2..cdf72e477 100644 --- a/docs/modules/ROOT/pages/appendix.adoc +++ b/docs/modules/ROOT/pages/appendix.adoc @@ -3,7 +3,6 @@ [[common-application-properties]] = Common application properties -include::_attributes.adoc[] Various properties can be specified inside your `application.properties` file, inside your `application.yml` file, or as command line switches. This appendix provides a list of common {project-full-name} properties and references to the underlying classes that consume them. @@ -11,4 +10,3 @@ This appendix provides a list of common {project-full-name} properties and refer NOTE: Property contributions can come from additional jar files on your classpath, so you should not consider this an exhaustive list. Also, you can define your own properties. -include::_configprops.adoc[] diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 503e0a538..e69de29bb 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1 +0,0 @@ -include::spring-cloud-openfeign.adoc[] diff --git a/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc b/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc index 50b765f5b..aab07bb00 100644 --- a/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc +++ b/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc @@ -1,10 +1,8 @@ [[spring-cloud-openfeign]] = Spring Cloud OpenFeign -include::_attributes.adoc[] *{spring-cloud-version}* -include::intro.adoc[] [[spring-cloud-feign]] From 28ba28337218d4a8a93740723fcd2e2e979019ac Mon Sep 17 00:00:00 2001 From: Olga MaciaszekSharma Date: Fri, 15 Sep 2023 18:10:24 +0200 Subject: [PATCH 08/10] Fix cross references --- docs/modules/ROOT/pages/spring-cloud-openfeign.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc b/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc index aab07bb00..28ffc708f 100644 --- a/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc +++ b/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc @@ -624,7 +624,7 @@ public class FooConfiguration { === Feign Capability support The Feign capabilities expose core Feign components so that these components can be modified. For example, the capabilities can take the `Client`, _decorate_ it, and give the decorated instance back to Feign. -The support for Micrometer is a good real-life example for this. See <>. +The support for Micrometer is a good real-life example for this. See xref:spring-cloud-openfeign.adoc#micrometer-support[Micrometer Support]. Creating one or more `Capability` beans and placing them in a `@FeignClient` configuration lets you register them and modify the behavior of the involved client. @@ -941,7 +941,7 @@ The URL provided in the configuration properties remains unused. [[aot-and-native-image-support]] === AOT and Native Image Support -Spring Cloud OpenFeign supports Spring AOT transformations and native images, however, only with refresh mode disabled, Feign clients refresh disabled (default setting) and <> disabled (default setting). +Spring Cloud OpenFeign supports Spring AOT transformations and native images, however, only with refresh mode disabled, Feign clients refresh disabled (default setting) and xref:spring-cloud-openfeign.adoc#attribute-resolution-mode[lazy `@FeignClient` attribute resolution] disabled (default setting). WARNING: If you want to run Spring Cloud OpenFeign clients in AOT or native image modes, make sure to set `spring.cloud.refresh.enabled` to `false`. From e54ba0532bcc4aa6fc2929f7166e82cca2e3ff94 Mon Sep 17 00:00:00 2001 From: Olga MaciaszekSharma Date: Fri, 15 Sep 2023 18:10:24 +0200 Subject: [PATCH 09/10] Enable Section Summary TOC for small pages --- docs/modules/ROOT/pages/appendix.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/modules/ROOT/pages/appendix.adoc b/docs/modules/ROOT/pages/appendix.adoc index cdf72e477..eef1c9056 100644 --- a/docs/modules/ROOT/pages/appendix.adoc +++ b/docs/modules/ROOT/pages/appendix.adoc @@ -2,6 +2,7 @@ [appendix] [[common-application-properties]] = Common application properties +:page-section-summary-toc: 1 Various properties can be specified inside your `application.properties` file, inside your `application.yml` file, or as command line switches. From 59b73c40403b803508387dbecbb76e44d8dfbca8 Mon Sep 17 00:00:00 2001 From: Olga MaciaszekSharma Date: Fri, 15 Sep 2023 18:49:12 +0200 Subject: [PATCH 10/10] Build Antora docs. --- .../workflows/deploy-docs.yml | 0 .gitignore | 6 ++ docs/antora-playbook.yml | 11 +--- docs/antora.yml | 4 +- docs/modules/ROOT/nav.adoc | 10 +--- docs/modules/ROOT/pages/_configprops.adoc | 37 ------------ docs/modules/ROOT/pages/appendix.adoc | 2 +- docs/modules/ROOT/pages/configprops.adoc | 6 ++ docs/modules/ROOT/pages/index.adoc | 9 +++ docs/modules/ROOT/pages/intro.adoc | 3 + .../ROOT/pages/spring-cloud-openfeign.adoc | 10 +--- docs/modules/ROOT/partials/_attributes.adoc | 3 + docs/pom.xml | 60 +++++++++++++++---- .../resources/antora-resources/antora.yml | 20 +++++++ .../pages => src/main/asciidoc}/README.adoc | 0 .../main/asciidoc}/sagan-boot.adoc | 0 .../main/asciidoc}/sagan-index.adoc | 0 17 files changed, 109 insertions(+), 72 deletions(-) rename {docs/.github => .github}/workflows/deploy-docs.yml (100%) delete mode 100644 docs/modules/ROOT/pages/_configprops.adoc create mode 100644 docs/modules/ROOT/pages/configprops.adoc create mode 100644 docs/modules/ROOT/partials/_attributes.adoc create mode 100644 docs/src/main/antora/resources/antora-resources/antora.yml rename docs/{modules/ROOT/pages => src/main/asciidoc}/README.adoc (100%) rename docs/{modules/ROOT/pages => src/main/asciidoc}/sagan-boot.adoc (100%) rename docs/{modules/ROOT/pages => src/main/asciidoc}/sagan-index.adoc (100%) diff --git a/docs/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml similarity index 100% rename from docs/.github/workflows/deploy-docs.yml rename to .github/workflows/deploy-docs.yml diff --git a/.gitignore b/.gitignore index 8a860b408..388132e87 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,9 @@ _site/ .vscode/ .flattened-pom.xml + +node +node_modules +build +package.json +package-lock.json diff --git a/docs/antora-playbook.yml b/docs/antora-playbook.yml index 9a70e676c..6cd8d6727 100644 --- a/docs/antora-playbook.yml +++ b/docs/antora-playbook.yml @@ -6,15 +6,10 @@ antora: - '@antora/collector-extension' - '@antora/atlas-extension' - require: '@springio/antora-extensions/root-component-extension' - root_component_name: 'PROJECT_WITHOUT_SPRING' - # FIXME: Run antora once using this extension to migrate to the Asciidoc Tabs syntax - # and then remove this extension - - require: '@springio/antora-extensions/tabs-migration-extension' - unwrap_example_block: always - save_result: true + root_component_name: 'cloud-openfeign' site: - title: PROJECT_FULL_NAME - url: https://docs.spring.io/PROJECT_NAME/reference/ + title: Spring Cloud Openfeign + url: https://docs.spring.io/spring-cloud-openfeign/reference/ content: sources: - url: ./.. diff --git a/docs/antora.yml b/docs/antora.yml index 15b346da0..dc2b1a7d4 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -1,6 +1,6 @@ -name: PROJECT_WITHOUT_SPRING +name: cloud-openfeign version: true -title: PROJECT_NAME +title: Spring Cloud OpenFeign nav: - modules/ROOT/nav.adoc ext: diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 5d5a53a8b..8769f9355 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,9 +1,5 @@ * xref:index.adoc[] -* xref:spring-cloud-openfeign.adoc[] -* xref:_attributes.adoc[] -* xref:intro.adoc[] -* xref:README.adoc[] -* xref:_configprops.adoc[] +** xref:intro.adoc[] +** xref:spring-cloud-openfeign.adoc[] * xref:appendix.adoc[] -* xref:sagan-boot.adoc[] -* xref:sagan-index.adoc[] +** xref:configprops.adoc[] diff --git a/docs/modules/ROOT/pages/_configprops.adoc b/docs/modules/ROOT/pages/_configprops.adoc deleted file mode 100644 index 6d8de12a4..000000000 --- a/docs/modules/ROOT/pages/_configprops.adoc +++ /dev/null @@ -1,37 +0,0 @@ -|=== -|Name | Default | Description - -|spring.cloud.openfeign.autoconfiguration.jackson.enabled | `false` | If true, PageJacksonModule and SortJacksonModule bean will be provided for Jackson page decoding. -|spring.cloud.openfeign.circuitbreaker.enabled | `false` | If true, an OpenFeign client will be wrapped with a Spring Cloud CircuitBreaker circuit breaker. -|spring.cloud.openfeign.circuitbreaker.group.enabled | `false` | If true, an OpenFeign client will be wrapped with a Spring Cloud CircuitBreaker circuit breaker with with group. -|spring.cloud.openfeign.client.config | | -|spring.cloud.openfeign.client.decode-slash | `true` | Feign clients do not encode slash `/` characters by default. To change this behavior, set the `decodeSlash` to `false`. -|spring.cloud.openfeign.client.default-config | `default` | -|spring.cloud.openfeign.client.default-to-properties | `true` | -|spring.cloud.openfeign.client.refresh-enabled | `false` | Enables options value refresh capability for Feign. -|spring.cloud.openfeign.compression.request.enabled | `false` | Enables the request sent by Feign to be compressed. -|spring.cloud.openfeign.compression.request.mime-types | `[text/xml, application/xml, application/json]` | The list of supported mime types. -|spring.cloud.openfeign.compression.request.min-request-size | `2048` | The minimum threshold content size. -|spring.cloud.openfeign.compression.response.enabled | `false` | Enables the response from Feign to be compressed. -|spring.cloud.openfeign.encoder.charset-from-content-type | `false` | Indicates whether the charset should be derived from the {@code Content-Type} header. -|spring.cloud.openfeign.httpclient.connection-timeout | `2000` | -|spring.cloud.openfeign.httpclient.connection-timer-repeat | `3000` | -|spring.cloud.openfeign.httpclient.disable-ssl-validation | `false` | -|spring.cloud.openfeign.httpclient.enabled | `true` | Enables the use of the Apache HTTP Client by Feign. -|spring.cloud.openfeign.httpclient.follow-redirects | `true` | -|spring.cloud.openfeign.httpclient.hc5.enabled | `false` | Enables the use of the Apache HTTP Client 5 by Feign. -|spring.cloud.openfeign.httpclient.hc5.pool-concurrency-policy | | Pool concurrency policies. -|spring.cloud.openfeign.httpclient.hc5.pool-reuse-policy | | Pool connection re-use policies. -|spring.cloud.openfeign.httpclient.hc5.socket-timeout | `5` | Default value for socket timeout. -|spring.cloud.openfeign.httpclient.hc5.socket-timeout-unit | | Default value for socket timeout unit. -|spring.cloud.openfeign.httpclient.max-connections | `200` | -|spring.cloud.openfeign.httpclient.max-connections-per-route | `50` | -|spring.cloud.openfeign.httpclient.ok-http.read-timeout | `60s` | {@link OkHttpClient} read timeout; defaults to 60 seconds. -|spring.cloud.openfeign.httpclient.time-to-live | `900` | -|spring.cloud.openfeign.httpclient.time-to-live-unit | | -|spring.cloud.openfeign.micrometer.enabled | `true` | Enables Micrometer capabilities for Feign. -|spring.cloud.openfeign.oauth2.enabled | `false` | Enables feign interceptor for managing oauth2 access token. -|spring.cloud.openfeign.oauth2.load-balanced | `false` | Enables load balancing for oauth2 access token provider. -|spring.cloud.openfeign.okhttp.enabled | `false` | Enables the use of the OK HTTP Client by Feign. - -|=== diff --git a/docs/modules/ROOT/pages/appendix.adoc b/docs/modules/ROOT/pages/appendix.adoc index eef1c9056..439fb7912 100644 --- a/docs/modules/ROOT/pages/appendix.adoc +++ b/docs/modules/ROOT/pages/appendix.adoc @@ -6,7 +6,7 @@ Various properties can be specified inside your `application.properties` file, inside your `application.yml` file, or as command line switches. -This appendix provides a list of common {project-full-name} properties and references to the underlying classes that consume them. +This appendix provides a list of common Spring Cloud OpenFeign properties and references to the underlying classes that consume them. NOTE: Property contributions can come from additional jar files on your classpath, so you should not consider this an exhaustive list. Also, you can define your own properties. diff --git a/docs/modules/ROOT/pages/configprops.adoc b/docs/modules/ROOT/pages/configprops.adoc new file mode 100644 index 000000000..32cbb8e58 --- /dev/null +++ b/docs/modules/ROOT/pages/configprops.adoc @@ -0,0 +1,6 @@ +[[configuration-properties]] += Configuration Properties + +Below you can find a list of configuration properties. + +include::partial$_configprops.adoc[] diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index e69de29bb..69cf1101a 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -0,0 +1,9 @@ +[[cloud-native-applications]] += Cloud Native Applications + +include::partial$_attributes.adoc[] + +// TODO: figure out remote includes in docs and replace pasted text +// include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing-docs.adoc[] +NOTE: Spring Cloud is released under the non-restrictive Apache 2.0 license. +If you would like to contribute to this section of the documentation or if you find an error, you can find the source code and issue trackers for the project at {github-issues}[github]. diff --git a/docs/modules/ROOT/pages/intro.adoc b/docs/modules/ROOT/pages/intro.adoc index a69a78c55..d837d0ebc 100644 --- a/docs/modules/ROOT/pages/intro.adoc +++ b/docs/modules/ROOT/pages/intro.adoc @@ -1,3 +1,6 @@ +[[intro]] += Introduction + This project provides OpenFeign integrations for Spring Boot apps through autoconfiguration and binding to the Spring Environment and other Spring programming model idioms. diff --git a/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc b/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc index 28ffc708f..0395700aa 100644 --- a/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc +++ b/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc @@ -1,9 +1,5 @@ -[[spring-cloud-openfeign]] -= Spring Cloud OpenFeign - -*{spring-cloud-version}* - - +[[features]] += Spring Cloud OpenFeign Features [[spring-cloud-feign]] == Declarative REST Client: Feign @@ -846,7 +842,7 @@ If Feign client refresh is enabled, each Feign client is created with: * `feign.Request.Options` as a refresh-scoped bean. This means properties such as `connectTimeout` and `readTimeout` can be refreshed against any Feign client instance. * A url wrapped under `org.springframework.cloud.openfeign.RefreshableUrl`. This means the URL of Feign client, if defined -with `spring.cloud.openfeign.client.config.{feignName}.url` property, can be refreshed against any Feign client instance. +with `spring.cloud.openfeign.client.config.\{feignName}.url` property, can be refreshed against any Feign client instance. You can refresh these properties through `POST /actuator/refresh`. diff --git a/docs/modules/ROOT/partials/_attributes.adoc b/docs/modules/ROOT/partials/_attributes.adoc new file mode 100644 index 000000000..959d40f4d --- /dev/null +++ b/docs/modules/ROOT/partials/_attributes.adoc @@ -0,0 +1,3 @@ +:sc-ext: java +:project-full-name: Spring Cloud OpenFeign +:all: {asterisk}{asterisk} diff --git a/docs/pom.xml b/docs/pom.xml index 23974a740..f95657253 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -3,25 +3,32 @@ xmlns="http://maven.apache.org/POM/4.0.0" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> 4.0.0 + org.springframework.cloud + spring-cloud-openfeign-docs org.springframework.cloud spring-cloud-openfeign 4.1.0-SNAPSHOT + .. https://github.com/spring-cloud/spring-cloud-openfeign - spring-cloud-openfeign-docs jar Spring Cloud OpenFeign Docs - Spring Cloud Docs + Spring Cloud OpenFeign Docs spring-cloud-openfeign ${basedir}/.. - feign.* - deploy + spring.cloud.* none + + + 1.0.2 + ${maven.multiModuleProjectDirectory}/ + .* + ${maven.multiModuleProjectDirectory}/docs/modules/ROOT/partials/ @@ -36,6 +43,12 @@ docs + + + src/main/antora/resources/antora-resources + true + + pl.project13.maven @@ -45,17 +58,44 @@ org.apache.maven.plugins maven-dependency-plugin - - org.apache.maven.plugins - maven-resources-plugin - org.codehaus.mojo exec-maven-plugin + + + + generate-observability-docs + ${generate-docs.phase} + + java + + + io.micrometer.docs.DocsGeneratorCommand + true + + ${micrometer-docs-generator.inputPath} + ${micrometer-docs-generator.inclusionPattern} + ${micrometer-docs-generator.outputPath} + + + + + + + io.micrometer + micrometer-docs-generator + ${micrometer-docs-generator.version} + jar + + + + + io.spring.maven.antora + antora-component-version-maven-plugin - org.asciidoctor - asciidoctor-maven-plugin + io.spring.maven.antora + antora-maven-plugin org.apache.maven.plugins diff --git a/docs/src/main/antora/resources/antora-resources/antora.yml b/docs/src/main/antora/resources/antora-resources/antora.yml new file mode 100644 index 000000000..9148923fa --- /dev/null +++ b/docs/src/main/antora/resources/antora-resources/antora.yml @@ -0,0 +1,20 @@ +version: @antora-component.version@ +prerelease: @antora-component.prerelease@ + +asciidoc: + attributes: + attribute-missing: 'warn' + chomp: 'all' + project-root: @maven.multiModuleProjectDirectory@ + github-repo: @docs.main@ + github-raw: https://raw.githubusercontent.com/spring-cloud/@docs.main@/@github-tag@ + github-code: https://github.com/spring-cloud/@docs.main@/tree/@github-tag@ + github-issues: https://github.com/spring-cloud/@docs.main@/issues/ + github-wiki: https://github.com/spring-cloud/@docs.main@/wiki + spring-cloud-version: @project.version@ + github-tag: @github-tag@ + version-type: @version-type@ + docs-url: https://docs.spring.io/@docs.main@/docs/@project.version@ + raw-docs-url: https://raw.githubusercontent.com/spring-cloud/@docs.main@/@github-tag@ + project-version: @project.version@ + project-name: @docs.main@ diff --git a/docs/modules/ROOT/pages/README.adoc b/docs/src/main/asciidoc/README.adoc similarity index 100% rename from docs/modules/ROOT/pages/README.adoc rename to docs/src/main/asciidoc/README.adoc diff --git a/docs/modules/ROOT/pages/sagan-boot.adoc b/docs/src/main/asciidoc/sagan-boot.adoc similarity index 100% rename from docs/modules/ROOT/pages/sagan-boot.adoc rename to docs/src/main/asciidoc/sagan-boot.adoc diff --git a/docs/modules/ROOT/pages/sagan-index.adoc b/docs/src/main/asciidoc/sagan-index.adoc similarity index 100% rename from docs/modules/ROOT/pages/sagan-index.adoc rename to docs/src/main/asciidoc/sagan-index.adoc