Spring/spring-boot
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Restructure spring-boot-docs packages

Browse Source 
Restructure the packages in `spring-boot-docs` so that they mirror
the documentation sections. There are now three main packages:
`springbootfeatures`, `productionreadyfeatures` and `howto`. Each
of the main packages has a subpackage named after the section headings.

Example code now uses consistent `// tag::` names and imports are
applied using `[tag=*]` whenever possible.

Test snippets have been moved to `src/main/java` so that only a single
import attribute needs to be defined.

Closes gh-25089
This commit is contained in:
Phillip Webb
2021-02-02 11:20:32 -08:00
parent db781a0d84
commit 91ccc23462
129 changed files with 1540 additions and 283 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
spring-boot-project/spring-boot-docs/src/docs/asciidoc/attributes.adoc
View File

@@ -20,8 +20,10 @@
:github-issues: https://github.com/{github-repo}/issues/
:github-wiki: https://github.com/{github-repo}/wiki
:code-examples: ../main/java/org/springframework/boot/docs
:test-examples: ../test/java/org/springframework/boot/docs
:include: ../main/java/org/springframework/boot/docs
:include-springbootfeatures: {include}/springbootfeatures
:include-productionreadyfeatures: {include}/productionreadyfeatures
:include-howto: {include}/howto
:spring-boot-code: https://github.com/{github-repo}/tree/{github-tag}
:spring-boot-api: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/api
@@ -94,9 +96,6 @@
:spring-session: https://spring.io/projects/spring-session
:spring-webservices-docs: https://docs.spring.io/spring-ws/docs/{spring-webservices-version}/reference/
:ant-docs: https://ant.apache.org/manual
:dependency-management-plugin-code: https://github.com/spring-gradle-plugins/dependency-management-plugin
:gradle-docs: https://docs.gradle.org/current/userguide

34
spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc
View File

@@ -95,7 +95,7 @@ For instance, the following example loads a YAML configuration file from the cla
[source,java,indent=0]
----
include::{code-examples}/context/EnvironmentPostProcessorExample.java[tag=example]
include::{include-howto}/springbootapplication/EnvironmentPostProcessorExample.java[tag=*]
----
TIP: The `Environment` has already been prepared with all the usual property sources that Spring Boot loads by default.
@@ -931,7 +931,7 @@ You can add an `org.apache.catalina.connector.Connector` to the `TomcatServletWe
[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
include::{code-examples}/context/embedded/TomcatMultipleConnectorsExample.java[tag=configuration]
include::{include-howto}/embeddedwebservers/TomcatMultipleConnectorsExample.java[tag=*]
----
@@ -951,7 +951,7 @@ To switch to the `LegacyCookieProcessor`, use an `WebServerFactoryCustomizer` be
[source,java,indent=0]
----
include::{code-examples}/context/embedded/TomcatLegacyCookieProcessorExample.java[tag=customizer]
include::{include-howto}/embeddedwebservers/TomcatLegacyCookieProcessorExample.java[tag=*]
----
@@ -978,7 +978,7 @@ Add an `UndertowBuilderCustomizer` to the `UndertowServletWebServerFactory` and
[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
include::{code-examples}/context/embedded/UndertowMultipleListenersExample.java[tag=configuration]
include::{include-howto}/embeddedwebservers/UndertowMultipleListenersExample.java[tag=*]
----
@@ -1283,7 +1283,7 @@ The `jersey.config.server.response.setStatusOverSendError` property must be set
[source,java,indent=0]
----
include::{code-examples}/jersey/JerseySetStatusOverSendErrorExample.java[tag=resource-config]
include::{include-howto}/jersey/JerseySetStatusOverSendErrorExample.java[tag=*]
----
@@ -1326,7 +1326,7 @@ The following example configures `HttpComponentsClientRequestFactory` with an `H
[source,java,indent=0]
----
include::{code-examples}/web/client/RestTemplateProxyCustomizationExample.java[tag=customizer]
include::{include-springbootfeatures}/resttemplate/RestTemplateProxyCustomizationExample.java[tag=*]
----
[[howto-webclient-reactor-netty-customization]]
@@ -1337,7 +1337,7 @@ The following example configures a 60 second connect timeout and adds a `ReadTim
[source,java,indent=0]
----
include::{code-examples}/web/reactive/function/client/ReactorNettyClientCustomizationExample.java[tag=custom-http-connector]
include::{include-howto}/httpclients/ReactorNettyClientCustomizationExample.java[tag=*]
----
TIP: Note the use of `ReactorResourceFactory` for the connection provider and event loop resources.
@@ -1582,7 +1582,7 @@ The following example shows how to create a data source by using a `DataSourceBu
[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
include::{code-examples}/jdbc/BasicDataSourceExample.java[tag=configuration]
include::{include-howto}/dataaccess/BasicDataSourceExample.java[tag=*]
----
To run an app with that `DataSource`, all you need is the connection information.
@@ -1623,7 +1623,7 @@ The following example shows how create a `HikariDataSource` with `DataSourceBuil
[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
include::{code-examples}/jdbc/SimpleDataSourceExample.java[tag=configuration]
include::{include-howto}/dataaccess/SimpleDataSourceExample.java[tag=*]
----
You can even go further by leveraging what `DataSourceProperties` does for you -- that is, by providing a default embedded database with a sensible username and password if no URL is provided.
@@ -1633,7 +1633,7 @@ To avoid that, you can redefine a custom `DataSourceProperties` on your custom n
[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
include::{code-examples}/jdbc/ConfigurableDataSourceExample.java[tag=configuration]
include::{include-howto}/dataaccess/ConfigurableDataSourceExample.java[tag=*]
----
This setup puts you _in sync_ with what Spring Boot does for you by default, except that a dedicated connection pool is chosen (in code) and its settings are exposed in the `app.datasource.configuration` sub namespace.
@@ -1670,7 +1670,7 @@ In the following example, we provide the _exact_ same feature set as the auto-co
[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
include::{code-examples}/jdbc/SimpleTwoDataSourcesExample.java[tag=configuration]
include::{include-howto}/dataaccess/SimpleTwoDataSourcesExample.java[tag=*]
----
TIP: `firstDataSourceProperties` has to be flagged as `@Primary` so that the database initializer feature uses your copy (if you use the initializer).
@@ -1700,7 +1700,7 @@ You can apply the same concept to the secondary `DataSource` as well, as shown i
[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
include::{code-examples}/jdbc/CompleteTwoDataSourcesExample.java[tag=configuration]
include::{include-howto}/dataaccess/CompleteTwoDataSourcesExample.java[tag=*]
----
The preceding example configures two data sources on custom namespaces with the same logic as Spring Boot would use in auto-configuration.
@@ -1794,7 +1794,7 @@ This implementation provides the same table structure as Hibernate 4: all dots a
[source,java,indent=0]
----
include::{code-examples}/jpa/CaseSensitiveSpringPhysicalNamingStrategyExample.java[tag=naming-strategy]
include::{include-howto}/dataaccess/CaseSensitiveSpringPhysicalNamingStrategyExample.java[tag=*]
----
If you prefer to use Hibernate 5's default instead, set the following property:
@@ -1828,7 +1828,7 @@ Then, add a `HibernatePropertiesCustomizer` bean as shown in the following examp
[source,java,indent=0]
----
include::{code-examples}/jpa/HibernateSecondLevelCacheExample.java[tag=configuration]
include::{include-howto}/dataaccess/HibernateSecondLevelCacheExample.java[tag=*]
----
This customizer will configure Hibernate to use the same `CacheManager` as the one that the application uses.
@@ -1969,7 +1969,7 @@ For example, if you use Hibernate Search with Elasticsearch as its index manager
[source,java,indent=0]
----
include::{code-examples}/elasticsearch/HibernateSearchElasticsearchExample.java[tag=configuration]
include::{include-howto}/dataaccess/HibernateSearchElasticsearchExample.java[tag=*]
----
@@ -2066,7 +2066,7 @@ You can initialize the database on startup using SQL scripts as shown in the fol
[source,java,indent=0]
----
include::{code-examples}/r2dbc/R2dbcDatabaseInitializationExample.java[tag=configuration]
include::{include-howto}/dataaccess/R2dbcDatabaseInitializationExample.java[tag=*]
----
Alternatively, you can configure either <<howto-execute-flyway-database-migrations-on-startup,Flyway>> or <<howto-execute-liquibase-database-migrations-on-startup,Liquibase>> to configure a `DataSource` for you for the duration of the migration.
@@ -2351,7 +2351,7 @@ The following example shows one way to write such an exporter:
[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
include::{code-examples}/actuate/metrics/MetricsHealthMicrometerExportExample.java[tag=configuration]
include::{include-howto}/actuator/MetricsHealthMicrometerExportExample.java[tag=*]
----

12
spring-boot-project/spring-boot-docs/src/docs/asciidoc/production-ready-features.adoc
View File

@@ -463,7 +463,7 @@ The following example exposes a read operation that returns a custom object:
[source,java,indent=0]
----
include::{code-examples}/actuate/endpoint/CustomEndpointExample.java[tag=read]
include::{include-productionreadyfeatures}/endpoints/CustomEndpointExample.java[tag=read]
----
You can also write technology-specific endpoints by using `@JmxEndpoint` or `@WebEndpoint`.
@@ -500,7 +500,7 @@ This can be used to invoke a write operation that takes `String name` and `int c
[source,java,indent=0]
----
include::{code-examples}/actuate/endpoint/CustomEndpointExample.java[tag=write]
include::{include-productionreadyfeatures}/endpoints/CustomEndpointExample.java[tag=write]
----
TIP: Because endpoints are technology agnostic, only simple types can be specified in the method signature.
@@ -2379,14 +2379,14 @@ To register custom metrics, inject `MeterRegistry` into your component, as shown
[source,java,indent=0]
----
include::{code-examples}/actuate/metrics/MetricsMeterRegistryInjectionExample.java[tag=component]
include::{include-productionreadyfeatures}/metrics/MetricsMeterRegistryInjectionExample.java[tag=*]
----
If your metrics depend on other beans, it is recommended that you use a `MeterBinder` to register them, as shown in the following example:
[source,java,indent=0]
----
include::{code-examples}/actuate/metrics/SampleMeterBinderConfiguration.java[tag=example]
include::{include-productionreadyfeatures}/metrics/SampleMeterBinderConfiguration.java[tag=*]
----
Using a `MeterBinder` ensures that the correct dependency relationships are set up and that the bean is available when the metric's value is retrieved.
@@ -2404,7 +2404,7 @@ For example, if you want to rename the `mytag.region` tag to `mytag.area` for al
[source,java,indent=0]
----
include::{code-examples}/actuate/metrics/MetricsFilterBeanExample.java[tag=configuration]
include::{include-productionreadyfeatures}/metrics/MetricsFilterBeanExample.java[tag=*]
----
@@ -2622,7 +2622,7 @@ For Tomcat, the following configuration can be added:
[source,java,indent=0]
----
include::{code-examples}/cloudfoundry/CloudFoundryCustomContextPathExample.java[tag=configuration]
include::{include-productionreadyfeatures}/cloudfoundry/CloudFoundryCustomContextPathExample.java[tag=*]
----

62
spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc
View File

@@ -195,7 +195,7 @@ The `SpringApplicationBuilder` lets you chain together multiple method calls and
[source,java,indent=0]
----
include::{code-examples}/builder/SpringApplicationBuilderExample.java[tag=hierarchy]
include::{include-springbootfeatures}/springapplication/SpringApplicationBuilderExample.java[tag=*]
----
NOTE: There are some restrictions when creating an `ApplicationContext` hierarchy.
@@ -436,7 +436,7 @@ This exit code can then be passed to `System.exit()` to return it as a status co
[source,java,indent=0]
----
include::{code-examples}/ExitCodeApplication.java[tag=example]
include::{include-springbootfeatures}/springapplication/ExitCodeExample.java[tag=*]
----
Also, the `ExitCodeGenerator` interface may be implemented by exceptions.
@@ -1673,7 +1673,7 @@ You may want to rename your custom `ConversionService` if it is not required for
[[boot-features-external-config-conversion-duration]]
===== Converting durations
===== Converting Durations
Spring Boot has dedicated support for expressing durations.
If you expose a `java.time.Duration` property, the following formats in application properties are available:
@@ -1685,7 +1685,7 @@ Consider the following example:
[source,java,indent=0]
----
include::{code-examples}/context/properties/bind/javabean/AppSystemProperties.java[tag=example]
include::{include-springbootfeatures}/externalizedconfiguration/duration/javabeanbinding/AppSystemProperties.java[tag=*]
----
To specify a session timeout of 30 seconds, `30`, `PT30S` and `30s` are all equivalent.
@@ -1708,7 +1708,7 @@ If you prefer to use constructor binding, the same properties can be exposed, as
[source,java,indent=0]
----
include::{code-examples}/context/properties/bind/constructor/AppSystemProperties.java[tag=example]
include::{include-springbootfeatures}/externalizedconfiguration/duration/constructorbinding/AppSystemProperties.java[tag=*]
----
@@ -1749,7 +1749,7 @@ Consider the following example:
[source,java,indent=0]
----
include::{code-examples}/context/properties/bind/javabean/AppIoProperties.java[tag=example]
include::{include-springbootfeatures}/externalizedconfiguration/datasize/javabeanbinding/AppIoProperties.java[tag=*]
----
To specify a buffer size of 10 megabytes, `10` and `10MB` are equivalent.
@@ -1770,7 +1770,7 @@ If you prefer to use constructor binding, the same properties can be exposed, as
[source,java,indent=0]
----
include::{code-examples}/context/properties/bind/constructor/AppIoProperties.java[tag=example]
include::{include-springbootfeatures}/externalizedconfiguration/datasize/constructorbinding/AppIoProperties.java[tag=*]
----
TIP: If you are upgrading a `Long` property, make sure to define the unit (using `@DataSizeUnit`) if it isn't bytes.
@@ -3515,7 +3515,7 @@ The following example shows how to customize `TomcatServletWebServerFactory` tha
[source,java,indent=0,subs="verbatim,quotes,attributes"]
----
include::{code-examples}/context/embedded/TomcatServerCustomizerExample.java[tag=configuration]
include::{include-springbootfeatures}/webapplications/TomcatServerCustomizerExample.java[tag=*]
----
@@ -3769,7 +3769,7 @@ For example, you can customize your security configuration by adding something l
[source,java,indent=0]
----
include::{code-examples}/web/security/CustomWebFluxSecurityExample.java[tag=configuration]
include::{include-springbootfeatures}/security/CustomWebFluxSecurityExample.java[tag=*]
----
@@ -4924,7 +4924,7 @@ To enable transaction management, the following bean must be defined in your con
[source,java,indent=0]
----
include::{code-examples}/neo4j/Neo4jReactiveTransactionManagerExample.java[tag=configuration]
include::{include-springbootfeatures}/nosql/Neo4jReactiveTransactionManagerExample.java[tag=*]
----
====
@@ -5609,7 +5609,7 @@ The following example shows a customizer that configures a specific entry expira
[source,java,indent=0]
----
include::{code-examples}/cache/CouchbaseCacheManagerCustomizationExample.java[tag=configuration]
include::{include-springbootfeatures}/nosql/CouchbaseCacheManagerCustomizationExample.java[tag=*]
----
@@ -5640,7 +5640,7 @@ The following example shows a customizer that configures a specific time to live
[source,java,indent=0]
----
include::{code-examples}/cache/RedisCacheManagerCustomizationExample.java[tag=configuration]
include::{include-springbootfeatures}/nosql//RedisCacheManagerCustomizationExample.java[tag=*]
----
@@ -6208,7 +6208,7 @@ To use the factory bean, wire `StreamsBuilder` into your `@Bean` as shown in the
[source,java,indent=0]
----
include::{code-examples}/kafka/KafkaStreamsBeanExample.java[tag=configuration]
include::{include-springbootfeatures}/messaging/KafkaStreamsBeanExample.java[tag=*]
----
By default, the streams managed by the `StreamBuilder` object it creates are started automatically.
@@ -6363,7 +6363,7 @@ The following example shows a customizer that configures the use of a proxy for
[source,java,indent=0]
----
include::{code-examples}/web/client/RestTemplateProxyCustomizationExample.java[tag=customizer]
include::{include-springbootfeatures}/resttemplate/RestTemplateProxyCustomizationExample.java[tag=*]
----
Finally, you can also create your own `RestTemplateBuilder` bean.
@@ -6372,7 +6372,7 @@ The following example exposes a `RestTemplateBuilder` with what Spring Boot woul
[source,java,indent=0]
----
include::{code-examples}/web/client/RestTemplateBuilderCustomizationExample.java[tag=customizer]
include::{include-springbootfeatures}/resttemplate/RestTemplateBuilderCustomizationExample.java[tag=*]
----
The most extreme (and rarely used) option is to create your own `RestTemplateBuilder` bean without using a configurer.
@@ -7025,7 +7025,7 @@ have `@SpringBootTest` inject them using the `args` attribute.
[source,java,indent=0]
----
include::{code-examples}/test/context/ApplicationArgumentsExampleTests.java[tag=example]
include::{include-springbootfeatures}/testing/ApplicationArgumentsExampleTests.java[tag=*]
----
@@ -7037,7 +7037,7 @@ If you have web endpoints that you want to test against this mock environment, y
[source,java,indent=0]
----
include::{code-examples}/test/web/MockMvcExampleTests.java[tag=test-mock-mvc]
include::{include-springbootfeatures}/testing/MockMvcExampleTests.java[tag=*]
----
TIP: If you want to focus only on the web layer and not start a complete `ApplicationContext`, consider <<boot-features-testing-spring-boot-applications-testing-autoconfigured-mvc-tests,using `@WebMvcTest` instead>>.
@@ -7046,7 +7046,7 @@ Alternatively, you can configure a {spring-framework-docs}/testing.html#webtestc
[source,java,indent=0]
----
include::{code-examples}/test/web/MockWebTestClientExampleTests.java[tag=test-mock-web-test-client]
include::{include-springbootfeatures}/testing/MockWebTestClientExampleTests.java[tag=*]
----
[TIP]
@@ -7071,7 +7071,7 @@ For convenience, tests that need to make REST calls to the started server can ad
[source,java,indent=0]
----
include::{code-examples}/test/web/RandomPortWebTestClientExampleTests.java[tag=test-random-port]
include::{include-springbootfeatures}/testing/RandomPortWebTestClientExampleTests.java[tag=*]
----
This setup requires `spring-webflux` on the classpath.
@@ -7079,7 +7079,7 @@ If you can't or won't add webflux, Spring Boot also provides a `TestRestTemplate
[source,java,indent=0]
----
include::{code-examples}/test/web/RandomPortTestRestTemplateExampleTests.java[tag=test-random-port]
include::{include-springbootfeatures}/testing/RandomPortTestRestTemplateExampleTests.java[tag=*]
----
@@ -7098,7 +7098,7 @@ If such test needs access to an `MBeanServer`, consider marking it dirty as well
[source,java,indent=0]
----
include::{test-examples}/jmx/SampleJmxTests.java[tag=test]
include::{include-springbootfeatures}/testing/jmx/SampleJmxTests.java[tag=*]
----
@@ -7921,14 +7921,14 @@ You can inject it by using `@Autowired` and use it in your tests as you normally
[source,java,indent=0]
----
include::{code-examples}/test/autoconfigure/restdocs/webclient/UsersDocumentationTests.java[tag=source]
include::{include-springbootfeatures}/testing/restdocs/webclient/UsersDocumentationTests.java[tag=*]
----
If you require more control over Spring REST Docs configuration than offered by the attributes of `@AutoConfigureRestDocs`, you can use a `RestDocsWebTestClientConfigurationCustomizer` bean, as shown in the following example:
[source,java,indent=0]
----
include::{code-examples}/test/autoconfigure/restdocs/webclient/AdvancedConfigurationExample.java[tag=configuration]
include::{include-springbootfeatures}/testing/restdocs/webclient/AdvancedConfigurationExample.java[tag=*]
----
@@ -7940,14 +7940,14 @@ You can inject it by using `@Autowired` and use it in your tests as you normally
[source,java,indent=0]
----
include::{code-examples}/test/autoconfigure/restdocs/restassured/UserDocumentationTests.java[tag=source]
include::{include-springbootfeatures}/testing/restdocs/restassured/UserDocumentationTests.java[tag=*]
----
If you require more control over Spring REST Docs configuration than offered by the attributes of `@AutoConfigureRestDocs`, a `RestDocsRestAssuredConfigurationCustomizer` bean can be used, as shown in the following example:
[source,java,indent=0]
----
include::{code-examples}/test/autoconfigure/restdocs/restassured/AdvancedConfigurationExample.java[tag=configuration]
include::{include-springbootfeatures}/testing/restdocs/restassured/AdvancedConfigurationExample.java[tag=*]
----
@@ -8141,7 +8141,7 @@ To use add `@ExtendWith(OutputCaptureExtension.class)` and inject `CapturedOutpu
[source,java,indent=0]
----
include::{test-examples}/test/system/OutputCaptureTests.java[tag=test]
include::{include-springbootfeatures}/testing/OutputCaptureTests.java[tag=*]
----
@@ -8186,7 +8186,7 @@ Any URLs that do not specify a host and port automatically connect to the embedd
[source,java,indent=0]
----
include::{test-examples}/web/client/SampleWebClientTests.java[tag=test]
include::{include-springbootfeatures}/testing/webclient/SampleWebClientTests.java[tag=*]
----
@@ -8450,7 +8450,7 @@ The following example makes sure that `UserServiceAutoConfiguration` is always i
[source,java,indent=0]
----
include::{test-examples}/autoconfigure/UserServiceAutoConfigurationTests.java[tag=runner]
include::{include-springbootfeatures}/testing/UserServiceAutoConfigurationTests.java[tag=runner]
----
TIP: If multiple auto-configurations have to be defined, there is no need to order their declarations as they are invoked in the exact same order as when running the application.
@@ -8461,14 +8461,14 @@ Invoking `run` provides a callback context that can be used with `AssertJ`.
[source,java,indent=0]
----
include::{test-examples}/autoconfigure/UserServiceAutoConfigurationTests.java[tag=test-user-config]
include::{include-springbootfeatures}/testing/UserServiceAutoConfigurationTests.java[tag=test-user-config]
----
It is also possible to easily customize the `Environment`, as shown in the following example:
[source,java,indent=0]
----
include::{test-examples}/autoconfigure/UserServiceAutoConfigurationTests.java[tag=test-env]
include::{include-springbootfeatures}/testing/UserServiceAutoConfigurationTests.java[tag=test-env]
----
The runner can also be used to display the `ConditionEvaluationReport`.
@@ -8502,7 +8502,7 @@ In the following example, we assert that if `UserService` is not present, the au
[source,java,indent=0]
----
include::{test-examples}/autoconfigure/UserServiceAutoConfigurationTests.java[tag=test-classloader]
include::{include-springbootfeatures}/testing/UserServiceAutoConfigurationTests.java[tag=test-classloader]
----