Merge pull request #12073 from Sébastien Deleuze

* gh-12073:
  Polish "Add Kotlin support reference documentation"
  Add Kotlin support reference documentation

spring-boot-project/spring-boot-docs/src/main/asciidoc/index.adoc

@@ -15,6 +15,7 @@ Phillip Webb; Dave Syer; Josh Long; Stéphane Nicoll; Rob Winch; Andy Wilkinson;
 :github-repo: spring-projects/spring-boot
 :github-raw: https://raw.github.com/{github-repo}/{github-tag}
 :github-code: https://github.com/{github-repo}/tree/{github-tag}
+:github-issues: https://github.com/{github-repo}/issues/
 :github-wiki: https://github.com/{github-repo}/wiki
 :github-master-code: https://github.com/{github-repo}/tree/master
 :sc-ext: java
@@ -68,6 +69,8 @@ Phillip Webb; Dave Syer; Josh Long; Stéphane Nicoll; Rob Winch; Andy Wilkinson;
 :jetty-documentation: https://www.eclipse.org/jetty/documentation/9.4.x
 :micrometer-concepts-documentation: https://micrometer.io/docs/concepts
 :tomcat-documentation: https://tomcat.apache.org/tomcat-8.5-doc
+:kotlin-documentation: https://kotlinlang.org/docs/reference/
+:junit5-documentation: https://junit.org/junit5/docs/current/user-guide
 // ======================================================================================
 
 include::documentation-overview.adoc[]

spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc

@@ -7534,6 +7534,225 @@ Boot's core features will be honoured by the presence of the core starter.
 
 
 
+[[boot-features-kotlin]]
+== Kotlin support
+https://kotlinlang.org[Kotlin] is a statically-typed language targeting the JVM (and other
+platforms) which allows writing concise and elegant code while providing
+{kotlin-documentation}java-interop.html[interoperability] with existing libraries written
+in Java.
+
+Spring Boot provides Kotlin support by leveraging the support in other Spring projects
+such as Spring Framework, Spring Data, and Reactor. See the
+{spring-reference}languages.html#kotlin[Spring Framework Kotlin support documentation]
+for more information.
+
+The easiest way to start with Spring Boot and Kotlin is to create a project via
+https://start.spring.io/#!language=kotlin[start.spring.io]. Feel free to join the #spring
+channel of http://slack.kotlinlang.org/[Kotlin Slack] or ask a question with `spring`
+and `kotlin` tags on https://stackoverflow.com/questions/tagged/spring+kotlin[Stack
+Overflow] if you need support.
+
+
+
+[[boot-features-kotlin-requirements]]
+=== Requirements
+Spring Boot supports Kotlin 1.2.x. To use Kotlin, `org.jetbrains.kotlin:kotlin-stdlib` and
+`org.jetbrains.kotlin:kotlin-reflect` must be present on the classpath. The
+`kotlin-stdlib` variants `kotlin-stdlib-jdk7` and `kotlin-stdlib-jdk8` can also be used.
+
+Since https://discuss.kotlinlang.org/t/classes-final-by-default/166[Kotlin classes are
+final by default], you are likely to want to configure
+{kotlin-documentation}compiler-plugins.html#spring-support[kotlin-spring]
+plugin in order to automatically open Spring-annotated classes so that they can be
+proxied.
+
+https://github.com/FasterXML/jackson-module-kotlin[Jackson's Kotlin module] is required
+for serializing / deserializing JSON data in Kotlin. It is automatically registered when
+found on the classpath. A warning message is logged if Jackson and Kotlin are present but
+the Jackson Kotlin module is not.
+
+TIP: These dependencies and plugins are provided by default if one bootstraps a Kotlin
+project on https://start.spring.io/#!language=kotlin[start.spring.io].
+
+
+
+[[boot-features-kotlin-null-safety]]
+=== Null-safety
+One of Kotlin's key features is {kotlin-documentation}null-safety.html[null-safety]. It
+deals with `null` values at compile time rather than deferring the problem to runtime and
+encountering a `NullPointerException`. This helps to eliminate a common source of bugs
+without paying the cost of wrappers like `Optional`. Kotlin also allows using functional
+constructs with nullable values as described in this
+http://www.baeldung.com/kotlin-null-safety[comprehensive guide to null-safety in Kotlin].
+
+Although Java does not allow one to express null-safety in its type system, Spring
+Framework, Spring Data, and Reactor now provide null-safety of their API via
+tooling-friendly annotations. By default, types from Java APIs used in Kotlin are
+recognized as
+{kotlin-documentation}java-interop.html#null-safety-and-platform-types[platform types]
+for which null-checks are relaxed.
+{kotlin-documentation}java-interop.html#jsr-305-support[Kotlin's support for JSR 305
+annotations] combined with nullability annotations provide null-safety for the related
+Spring API in Kotlin.
+
+The JSR 305 checks can be configured by adding the `-Xjsr305` compiler flag with the
+following options: `-Xjsr305={strict|warn|ignore}`. The default behavior is the same as
+`-Xjsr305=warn`. The `strict` value is required to have null-safety taken in account in
+Kotlin types inferred from Spring API but should be used with the knowledge that Spring
+API nullability declaration could evolve even between minor releases and more checks may
+be added in the future).
+
+WARN: Generic type arguments, varargs and array elements nullability are not yet
+supported. See https://jira.spring.io/browse/SPR-15942[SPR-15942] for up-to-date
+information. Also be aware that Spring Boot's own API is {github-issues}10712[not yet
+annotated].
+
+
+
+[[boot-features-kotlin-api]]
+=== Kotlin API
+
+
+
+[[boot-features-kotlin-api-runapplication]]
+==== runApplication
+Spring Boot provides an idiomatic way to run an application with
+`runApplication<FooApplication>(*args)` as shown in the following example:
+
+[source,kotlin,indent=0]
+----
+import org.springframework.boot.autoconfigure.SpringBootApplication
+import org.springframework.boot.runApplication
+
+@SpringBootApplication
+class FooApplication
+
+fun main(args: Array<String>) {
+	runApplication<FooApplication>(*args)
+}
+----
+
+This is a drop-in replacement for
+`SpringApplication.run(FooApplication::class.java, *args)`. It also allows customization
+of the application as shown in the following example:
+
+[source,kotlin,indent=0]
+----
+runApplication<FooApplication>(*args) {
+	setBannerMode(OFF)
+}
+----
+
+
+
+[[boot-features-kotlin-api-extensions]]
+==== Extensions
+Kotlin {kotlin-documentation}extensions.html[extensions] provide the ability
+to extend existing classes with additional functionality. The Spring Boot Kotlin API makes
+use of these extensions to add new Kotlin specific conveniences to existing APIs.
+
+`TestRestTemplate` extensions, similar to those provided by Spring Framework for
+`RestOperations` in Spring Framework, are provided. Among other things, the extensions
+make it possible to take advantage of Kotlin reified type parameters.
+
+
+
+[[boot-features-kotlin-dependency-management]]
+=== Dependency management
+In order to avoid mixing different version of Kotlin dependencies on the classpath,
+dependency management of the following Kotlin dependencies is provided:
+
+ - `kotlin-reflect`
+ - `kotlin-runtime`
+ - `kotlin-stdlib`
+ - `kotlin-stdlib-jdk7`
+ - `kotlin-stdlib-jdk8`
+ - `kotlin-stdlib-jre7`
+ - `kotlin-stdlib-jre8`
+
+With Maven, the Kotlin version can be customized via the `kotlin.version` property and
+plugin management is provided for `kotlin-maven-plugin`. With Gradle, the Spring Boot
+plugin automatically aligns the `kotlin.version` with the version of the Kotlin plugin.
+
+
+
+[[boot-features-kotlin-configuration-properties]]
+=== `@ConfigurationProperties`
+`@ConfigurationProperties` currently only works with `lateinit` or nullable `var`
+properties (the former is recommended), since immutable classes initialized by
+constructors are {github-issues}8762[not yet supported].
+
+[source,kotlin,indent=0]
+----
+@ConfigurationProperties("example.kotlin")
+class KotlinExampleProperties {
+
+	lateinit var foo1: String
+
+	lateinit var foo2: String
+
+	lateinit val bar = Bar()
+
+	class Bar {
+
+		lateinit var bar1: String
+
+		lateinit var bar2: String
+
+	}
+
+}
+----
+
+
+[[boot-features-kotlin-testing]]
+=== Testing
+While it is possible to use JUnit 4 (the default provided by `spring-boot-starter-test`)
+to test Kotlin code, JUnit 5 is recommended. JUnit 5 enables a test class to be
+instantiated once and reused for all of the class's tests. This makes it possible to use
+`@BeforeAll` and `@AfterAll` annotations on non-static methods, which is a good fit for
+Kotlin.
+
+To use JUnit 5, exclude `junit:junit` dependency from `spring-boot-starter-test`, add
+JUnit 5 dependencies, and configure the Maven or Gradle plugin accordingly. See the
+{junit5-documentation}/#dependency-metadata-junit-jupiter-samples[JUnit 5
+documentation] for more details. You also need to
+{junit5-documentation}/#writing-tests-test-instance-lifecycle-changing-default[switch test
+instance lifecycle to "per-class"].
+
+
+
+[[boot-features-kotlin-resources]]
+=== Resources
+
+
+
+[[boot-features-kotlin-resources-further-reading]]
+==== Further reading
+* {kotlin-documentation}[Kotlin language reference]
+* http://slack.kotlinlang.org/[Kotlin Slack] (with a dedicated #spring channel)
+* https://stackoverflow.com/questions/tagged/spring+kotlin[Stackoverflow with `spring` and `kotlin` tags]
+* https://try.kotlinlang.org/[Try Kotlin in your browser]
+* https://blog.jetbrains.com/kotlin/[Kotlin blog]
+* https://kotlin.link/[Awesome Kotlin]
+* https://spring.io/blog/2016/02/15/developing-spring-boot-applications-with-kotlin[Developing Spring Boot applications with Kotlin]
+* https://spring.io/blog/2016/03/20/a-geospatial-messenger-with-kotlin-spring-boot-and-postgresql[A Geospatial Messenger with Kotlin, Spring Boot and PostgreSQL]
+* https://spring.io/blog/2017/01/04/introducing-kotlin-support-in-spring-framework-5-0[Introducing Kotlin support in Spring Framework 5.0]
+* https://spring.io/blog/2017/08/01/spring-framework-5-kotlin-apis-the-functional-way[Spring Framework 5 Kotlin APIs, the functional way]
+
+
+
+[[boot-features-kotlin-resources-examples]]
+==== Examples
+
+* https://github.com/sdeleuze/spring-boot-kotlin-demo[spring-boot-kotlin-demo]: regular Spring Boot + Spring Data JPA project
+* https://github.com/mixitconf/mixit[mixit]: Spring Boot 2 + WebFlux + Reactive Spring Data MongoDB
+* https://github.com/sdeleuze/spring-kotlin-fullstack[spring-kotlin-fullstack]: WebFlux Kotlin fullstack example with Kotlin2js for frontend instead of JavaScript or TypeScript
+* https://github.com/spring-petclinic/spring-petclinic-kotlin[spring-petclinic-kotlin]: Kotlin version of the Spring PetClinic Sample Application
+* https://github.com/sdeleuze/spring-kotlin-deepdive[spring-kotlin-deepdive]: a step by step migration for Boot 1.0 + Java to Boot 2.0 + Kotlin
+
+
+
 [[boot-features-whats-next]]
 == What to Read Next
 If you want to learn more about any of the classes discussed in this section, you can