diff --git a/initializr-docs/pom.xml b/initializr-docs/pom.xml index 4230d993..37a4de90 100644 --- a/initializr-docs/pom.xml +++ b/initializr-docs/pom.xml @@ -103,6 +103,7 @@ true ${project.version} ${project.version} + ${spring.boot.version} ${snippets.location} ${github-tag} @@ -192,25 +193,7 @@ - - pdf - - generate-pdf - - prepare-package - - ${basedir}/src/main/docbook/xsl/pdf.xsl - ${basedir}/target/docbook/pdf - - - - - - - - - - + epub diff --git a/initializr-docs/src/main/asciidoc/configuration-guide.adoc b/initializr-docs/src/main/asciidoc/configuration-guide.adoc new file mode 100644 index 00000000..0b313f4a --- /dev/null +++ b/initializr-docs/src/main/asciidoc/configuration-guide.adoc @@ -0,0 +1,387 @@ +[[configuration-guide]] += Configuration Guide + +[partintro] +-- +This section describes how you can create your own instance of the service and tune it for +your needs. You'll also find some advanced tips to make sure the available options are +consistent with the chosen Spring Boot generation. +-- + + + +[[create-instance]] +== Creating your own instance +Spring Initializr is split in three main modules: + +* `initializr-generator`: standalone project generation library that can be reused in +many environments (including embedded in your own project) +* `initializr-web`: REST endpoints and web interface +* `initializr-actuator`: optional module to provide statistics and metrics on project +generation + +Because it contains several auto-configurations, creating your own instance is quite easy, +actually you could get started using Spring Initializr itself! + +Create a new project with the `web` dependency and add the following dependency: + +[source,xml,indent=0,subs="verbatim,attributes"] +---- + + io.spring.initializr + initializr-web + {spring-initializr-version} + +---- + +Or if you are using Gradle: + +[source,groovy,indent=0,subs="verbatim,quotes,attributes"] +---- +compile("io.spring.initializr:initializr-web:{spring-initializr-version}") +---- + +If you start the application, you'll see the familiar interface but none of the drop down +lists have values (except the one for the Spring Boot version, we will +<>). In the rest of this section, +we will configure those basic settings. + +[TIP] +==== +Most of the settings are configured via `application.properties` using the `initializr` +namespace. Because the configuration is highly hierarchical, we recommend using the yaml +format that is more readable for such structure. If you agree, go ahead and rename +`application.properties` to `application.yml`. +==== + + + +[[create-instance-basic-settings]] +=== Configuring basic settings +Most of the drop-down lists are configured via a simple list-based structure where each +entry has an `id`, a `name` and whether that entry is the default or not. If no `name` is +provided, the `id` is used instead. + +Let's configure the languages and the Java versions we want to support: + +[source,yaml,indent=0] +---- + initializr: + javaVersions: + - id: 9 + default: false + - id: 1.8 + default: true + languages: + - name: Java + id: java + default: true + - name: Kotlin + id: kotlin + default: false +---- + +If you click on the "Switch to the full version" link, the two drop down lists now offer +the options and default values defined above. + +Spring Initializr supports `java`, `groovy` and `kotlin` and additional languages can be +added in your own customization. + +The available packagings are also configurable that way: + +[source,yaml,indent=0] +---- + initializr: + packagings: + - name: Jar + id: jar + default: true + - name: War + id: war + default: false +---- + +These two packaging types are the only one explicitly supported at the moment. + + + +[[create-instance-boot-versions]] +=== Configuring available Spring Boot versions +If you look at http://projects.spring.io/spring-boot[the project home page for Spring +Boot], the latest versions are displayed. And you've probably noticed that they match +the drop down list that you automatically get with a default instance. The reason for that +is that Spring Initializr requests an API on spring.io to retrieve the latest versions +automatically. This makes sure that you always get the latest available versions. + +If that's not what you want, you need to override the `InitializrMetadataProvider` bean +that is responsible to provide the metadata of the service. For instance, you could swap +to an implementation that always returns the content of your configuration file: + +[source,java,indent=0] +---- + @Bean + public InitializrMetadataProvider initializrMetadataProvider( + InitializrProperties properties) { + InitializrMetadata metadata = InitializrMetadataBuilder + .fromInitializrProperties(properties).build(); + return new SimpleInitializrMetadataProvider(metadata); + } +---- + +The thing to remember is that, by default, you don't have to worry about upgrading your +instance when a new Spring Boot version is released. However, you may need to +<> to avoid requesting that +service too often. + + + +[[create-instance-types]] +=== Configuring available project types +The available project types mostly define the structure of the generated project and its +build system. Once a project type is selected, the related action is invoked to generate +the project. + +By default, Spring Initializr exposes the following actions: + +* `/pom.xml` generate a Maven `pom.xml` +* `/build.gradle` generate a Gradle build +* `/starter.zip` generate a complete project structure archived in a zip +* `/starter.tgz` generate a complete project structure archived in a tgz + +Each type also defines one or more *tags*, that is additional metadata entries to qualify +the entry. The following standard tags exist: + +* `build`: the name of the build system to use (e.g. `maven`, `gradle`) +* `format`: the format of the project (e.g. `project` for a full project, `build` for just +a build file). + +By default, the HTML UI filters all the available types to only display the ones that have +a `format` tag with value `project`. + +You can of course implement additional endpoints that generate whatever project structure +you need but, for now, we'll simply configure our instance to generate a Gradle or a Maven +project: + +[source,yaml,indent=0] +---- + initializr: + types: + - name: Maven Project + id: maven-project + description: Generate a Maven based project archive + tags: + build: maven + format: project + default: true + action: /starter.zip + - name: Gradle Project + id: gradle-project + description: Generate a Gradle based project archive + tags: + build: gradle + format: project + default: false + action: /starter.zip +---- + +NOTE: If you intend to build a custom client against your service, you can add as +many tags as you want. + +The spring boot CLI uses them as a shortcut to the full id. So rather than having to +create a Gradle project as follows: + +[indent=0,subs="verbatim,quotes,attributes"] +---- + $ spring init --type=gradle-project my-project.zip +---- + +You can simply define a more convenient build parameter: + +[indent=0,subs="verbatim,quotes,attributes"] +---- + $ spring init --build=gradle my-project.zip +---- + + +With that configuration, you should be able to generate your first project, +congratulations! Let's now add dependencies so that you can start searching for them. + + + +[[create-instance-dependencies]] +=== Configuring dependencies +The most basic `dependency` is composed of: + +* An `id` used in clients to refer to it +* The full maven coordinates of the dependency (`groupId` and `artifactId`) +* A display `name` (used in the UI and the search results) +* A `description` can (and should) be added to provide more information about the +dependency + +Spring Initializr automatically considers that a dependency without maven coordinates +defines an official Spring Boot starter. In such a case, the `id` is used to infer the +`artifactId`. + +For instance, the following configures the `spring-boot-starter-web` Starter: + +[source,yaml,indent=0] +---- + initializr: + dependencies: + - name: Web + content: + - name: Web + id: web + description: Full-stack web development with Tomcat and Spring MVC +---- + +Each dependency is contained in a _group_ that gathers dependencies sharing a common +surface area or any other form of grouping. In the example above, a `Web` group holds our +unique dependency. A group can also provide default values for various settings, see the +<> for more details. + +In our `spring-boot-starter-web` example above, the dependency is _managed_ by Spring +Boot so there is no need to provide a `version` attribute for it. You'll surely need to +define additional dependencies that are not provided by Spring Boot and we strongly +recommend you to use a <>. + +If no BOM is available you can specify a version directly: + +[source,yaml,indent=0] +---- + initializr: + dependencies: + - name: Tech + content: + - name: Acme + id: acme + groupId: com.example.acme + artifactId: acme + version: 1.2.0.RELEASE + description: A solid description for this dependency +---- + +If you add this configuration and search for "acme" (or "solid"), you'll find this extra +entry; generating a maven project with it should add the following to the pom + +[source,xml,indent=0,subs="verbatim"] +---- + + com.example.acme + acme + 1.2.0.RELEASE + +---- + +The rest of this section will detail the other configuration options. + + +[[dependencies-version-range]] +==== Availability (version range) + + +[[dependencies-mappings]] +==== Map coordinates according to the Spring Boot version + + +[[dependencies-alias]] +==== Aliases + + +[[dependencies-repository]] +==== Repository + +If the dependency is not available on Maven Central (or whatever default repository that +is configured on your end), you can also add a <>. + + +[[dependencies-facet]] +==== Facets + +[[create-instance-dependencies-link]] +==== Links + + +[[create-instance-dependencies-search]] +==== Improve search results + +Weight + keywords + + +[[create-instance-repositories]] +=== Configuring Repositories + + +[[create-instance-boms]] +=== Configuring Bill of Materials + + +[[configuration-howto]] +== '`How-to`' guides + +This section provides answers to some common '`how do I do that...`' type of questions +that often arise when configuring Spring Initializr. + +[[howto-dependency-starter-flag]] +=== Make sure a regular dependency brings the base starter + +[[howto-group-share-settings]] +=== Share common dependency settings in a group + + +[[create-instance-advanced-config]] +== Advanced configuration + + + +[[create-instance-advanced-config-caching]] +=== Caching configuration +If you use the service, you'll notice that the logs have lots of entries with the message +`Fetching boot metadata from https://spring.io/project_metadata/spring-boot`. To avoid +checking for the latest Spring Boot versions too often, you should enable caching on your +service. Spring Initializr has some auto-configuration to apply the proper caches if you +are willing to use a JCache (JSR-107) implementation. + +Add the `javax.cache:cache-api` and your favorite JCache implementation and simply enable +caching by adding `@EnableCaching` to your `@SpringBootApplication`. For instance, you +could use `ehcache` by adding the following: + +[source,xml,indent=0,subs="verbatim,attributes"] +---- + + javax.cache + cache-api + + + org.ehcache + ehcache + +---- + +Or if you are using Gradle: + +[source,groovy,indent=0,subs="verbatim,quotes,attributes"] +---- +compile("javax.cache:cache-api") +compile("org.ehcache:ehcache") +---- + +You'll notice that the log entry is much more rare. If you do not want to use JSR-107, you +should configure the cache yourselves: + +.Cache configuration +|=== +| cache name | Description + +|`initializr` +|Cache the full metadata of the service. When the metadata expires, it is fully resolved +again (including a check on spring.io for the latest Spring Boot versions). Adapt the +expiration settings accordingly. + +|`project-resources` +|Cache resources that are used to generate projects. + +|`dependency-metadata` +|Cache dependency-specific metadata. +|=== diff --git a/initializr-docs/src/main/asciidoc/documentation-overview.adoc b/initializr-docs/src/main/asciidoc/documentation-overview.adoc index 768a517c..b4107eae 100644 --- a/initializr-docs/src/main/asciidoc/documentation-overview.adoc +++ b/initializr-docs/src/main/asciidoc/documentation-overview.adoc @@ -1,19 +1,32 @@ -[[boot-documentation]] +[[initializr-documentation]] = Spring Initializr Documentation -Spring Initializr provides an extensible API to generate quickstart projects. It also -provides a configurable service: you can see our default instance at -https://start.spring.io. It provides a simple web UI to configure the project to -generate and endpoints that you can use via plain HTTP. +[partintro] +-- +This section provides a brief overview of Spring Initializr reference documentation. Think +of it as map for the rest of the document. Some sections are targeted to a specific +audience so this reference guide is not meant to be read in a linear fashion. +-- -Spring Initializr also exposes an endpoint that serves its metadata in a -<> to allow third-party -clients to provide the necessary assistance. +Spring Initializr provides an extensible API to generate quickstart projects. Such an API +can be used standalone or embedded in other tools. We also provide a configurable service: +you can see our default instance at https://start.spring.io. It provides a simple web UI +to configure the project to generate and endpoints that you can use via plain HTTP. -Finally, Initializr offers a <> to define all the aspects related to the project to -generate: list of dependencies, supported java and boot versions, etc. +The service allows you to customize the project to generate: the build system and its +coordinates, the language and version, the packaging and finally the dependencies to add +the project. The latter is a core concept: based on the chosen Spring Boot version, a set +of dependencies can be chosen, usually Spring Boot starters, that will have a concrete +impact on your application. More details in the <>. +You can easily create your own instance: there is minimal code involved and the service +has a very rich configuration structure, allowing you to define not only the values of +various project attributes but also the list of dependencies and the constraints to apply +to them. + +Spring Initializr also exposes an endpoint that serves its metadata in a well-known format +to allow third-party clients to provide the necessary assistance. Currently, all the major +Java IDEs are covered and you can generate a project right from your favourite IDE. [[initializr-documentation-about]] diff --git a/initializr-docs/src/main/asciidoc/index.adoc b/initializr-docs/src/main/asciidoc/index.adoc index 8b449f2a..2c07fe01 100644 --- a/initializr-docs/src/main/asciidoc/index.adoc +++ b/initializr-docs/src/main/asciidoc/index.adoc @@ -19,13 +19,11 @@ Stéphane Nicoll; Dave Syer :spring-initializr-docs-version: current :spring-initializr-docs: http://docs.spring.io/initializr/docs/{spring-initializr-docs-version}/reference :spring-initializr-docs-current: http://docs.spring.io/initializr/docs/current/reference - +:spring-boot-reference: http://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/reference/htmlsingle // ====================================================================================== -include::documentation-overview.adoc[leveloffset=+1] -include::metadata-format.adoc[leveloffset=+1] -include::using-the-stubs.adoc[leveloffset=+1] -include::configuration-format.adoc[leveloffset=+1] - +include::documentation-overview.adoc[] +include::user-guide.adoc[] +include::configuration-guide.adoc[] // ====================================================================================== diff --git a/initializr-docs/src/main/asciidoc/user-guide.adoc b/initializr-docs/src/main/asciidoc/user-guide.adoc new file mode 100644 index 00000000..a76e6658 --- /dev/null +++ b/initializr-docs/src/main/asciidoc/user-guide.adoc @@ -0,0 +1,226 @@ +[[user-guide]] += User Guide + +[partintro] +-- +If you're wondering how to use https://start.spring.io or what features are available, +this section is for you! You'll find the various way you can interact with the service and +get a better insight at what you can do with it. +-- + + + +[[getting-started]] +== Getting Started +Let's create a first project and discover the various options that you can use to tune it. +Go to https://start.spring.io, change the `Group` field from "com.example" to "org.acme" +and put the focus in the `Dependencies` field on the right hand side. If you type "web", +you will see a list of matching choices with that simple criteria. Use the mouse or the +arrow keys and `Enter` to select the "Web" starter. + +Your browser should now be in this state: + +TODO: add screenshot + +NOTE: The Spring Boot version above probably doesn't match the one you have. As we will +see later, start.spring.io is continuously updated as new Spring Boot versions are +published and the service uses the latest version by default. + +Click on `Generate Project`, this downloads a zip file containing a Maven project with +the following structure: + +``` +mvnw +mvnw.cmd +pom.xml +src +├── main +│   ├── java +│   │   └── org +│   │   └── acme +│   │   └── DemoApplication.java +│   └── resources +│   ├── application.properties +│   ├── static +│   └── templates +└── test + └── java + └── org + └── acme + └── DemoApplicationTests.java +``` + +A typical project generated by Spring Initializr contains a Spring Boot application +(`DemoApplication`), a test and an empty configuration. If you run the `main` method +of `DemoApplication`, you'll see an "empty" spring boot app starting on localhost:8080. + +Because Spring Initializr has detected it is a web application, a `static` and `templates` +directories have been created to hold your static resources and ui templates. + +Also, a Maven wrapper is automatically included so that you don't have to install Maven to +run this project. You can select Gradle instead in first drop down list. This will +generate a Gradle-based project instead that also contains a wrapper if you don't have +Gradle installed. + + + +[[getting-started-advanced-options]] +=== Advanced options +Next to the `Generate Project` you'll find a "Switch to the full version" link. If you +click on that, you'll see all the available options. Let's browse through them quickly: + +* *Group*: project coordinates (id of the project's group, as referred by the `groupId` +attribute in Apache Maven). Also infers the root package name to use. +* *Artifact*: project coordinates (id of the artifact, as referred by the `artifactId` +attribute in Apache Maven). Also infers the name of the project +* *Name*: display name of the project that also determines the name of your Spring Boot +application. For instance, if the name of your project is `my-app`, the generated project +will have a `MyAppApplication` class +* *Description*: description of the project +* *Package Name*: root package of the project. If not specified, the value of the *Group* +attribute is used +* *Packaging*: project packaging (as referred by the concept of the same name in Apache +Maven). start.spring.io can generate jar or war projects +* *Java Version*: the Java version to use +* *Language*: the programming language to use + +If you keep on scrolling, you'll discover all the dependencies that you can find using the +search box on the right. You'll probably notice that some dependencies aren't available +because they require a specific Spring Boot version. We'll tackle that in the next +section. + + + +[[getting-started-dependencies]] +=== Dependencies +The UI allows you to select the Spring Boot version you want to use. You may want to be +conservative and keep the default which corresponds at all times to the latest stable +release. Or you may want to chose a milestone of the next major version. Either way, +you'll notice that certain dependencies become available and others aren't anymore when +you change the version. + +If you are searching for a dependency that you know to be available and you get no result, +it's worth looking in the advanced section if that dependency is available in the Spring +Boot version that is currently selected. + +You may find it is not the case with a message that looks like the following: + +``` +requires Spring Boot >=1.0.0.RELEASE and <1.5.0.RC1 +``` + +Concretely, this defines a "version range" that states the dependency is deprecated and is +no longer available as of Spring Boot 1.5. You may want to check the release notes of the +related project to understand what your migration path can be. Alternatively, the message +could be: + +``` +requires Spring Boot >=2.0.0.RELEASE +``` + +That version range means the dependency is not available with the current Spring Boot +generation. Obviously, if you select Spring Boot 2.0 (or later if available), you'll be +able to select that dependency. + + + +[[getting-started-tuning-defaults]] +=== Tuning default values +The Initializr service is configured to offer default values so that you can generate a +new project with minimum fuss. Maybe you are a Kotlin fan? Or a Gradle fan? Currently +start.spring.io defaults to Java and Maven but it also allows you to tune these defaults +easily. + +You can share or bookmark URLs that will automatically customize form inputs. For +instance, the following URL changes the default to use Kotlin and Gradle: + +``` +https://start.spring.io/#!language=kotlin&type=gradle-project +``` + +TIP: `type` is the attribute of the first drop-down list where the type of project can +be selected and `gradle-project` is the id for the Gradle option. As you may guess, +`maven-project` is the id of the default (Maven) option. + + + +[[command-line]] +== Command line support +You can also generate a project in a shell using `cURL` or `HTTPie`. To discover the +available options of a particular instance, simply "curl it", i.e. if you have `curl` +installed invoke `curl start.spring.io` on the command-line (or alternatively +`http start.spring.io` if you prefer to use `HTTPie`). + +This provides a textual representation of the capabilities of the service that are split +in three sections: + +First, a table that describes the available project's types. On the default instance, +you'll find the `maven-project` and `gradle-project` we've discussed above but you'll +also be able to generate only a build script rather than an entire project. + +Then, a table that describes the available parameters. For the most part, these are the +same options as the ones available in the web UI. There are, however, a few additional +ones: + +* `applicationName` can be used to define the name of the application, disabling the +algorithm that infer it based on the `name` parameter +* `baseDir` can be used to create a base directory in the archive so that you can extract +the generated zip without creating a directory for it first + +Finally, the list of dependencies are defined. Each entry provides the identifier that +you'll have to use if you want to select the dependency, a description and the Spring Boot +version range, if any. + +Alongside the capabilities of the service, you'll also find a few examples that help you +understand how you can generate a project. These are obviously tailored to the client that +you are using. + +Let's assume that you want to generate a "my-project.zip" project based on Spring Boot +`1.5.2.RELEASE`, using the `web` and `devtools` dependencies (remember, those two ids are +displayed in the capabilities of the service): + +``` +$ curl https://start.spring.io/starter.zip -d dependencies=web,devtools \ + -d bootVersion=1.5.2.RELEASE -o my-project.zip +``` + +If you extract `my-project.zip`, you'll notice a few differences compared to what happens +with the web UI: + +* The project will be extracted in the current directory (the web UI adds a base directory +automatically with the same name as the one of the project) +* The name of the project is not `my-project` (the `-o` parameter has no incidence on the +name of the project) + +The exact same project can be generated using the `http` command as well: + +``` +$ http https://start.spring.io/starter.zip dependencies==web,devtools \ + bootVersion==1.5.1.RELEASE -d +``` + +NOTE: `HTTPie` reads the same hint as the browser so it will store a `demo.zip` file in +the current directory, with the same differences discussed above. + + + +[[ide]] +== IDEs support +Spring Initializr is also integrated in all major Java IDEs and allows you to create and +import a new project without having to leave the IDE for the command-line or the web UI. + +The following IDEs have dedicated support: +* Eclipse/STS +* IntelliJ IDEA (Ultimate Edition) +* NetBeans (using the + +Refer to the documentation of your favorite IDE for more details. + + + +[[spring-boot-cli]] +== Spring Boot CLI support +The `spring` command line tool defines an `init` command that allows you to create a +project using Spring Initializr. + +Check {spring-boot-reference}/#cli-init[the documentation for more details].