initializr/initializr-docs/src/main/asciidoc/user-guide.adoc

[[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:

image::web-selected.png[]

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 build it with `./mvnw install`). If you prefer, you can select
Gradle instead in the first drop down list at the top of the screen. This will generate a
Gradle-based project instead that also contains a wrapper if you don't have Gradle
installed (build it with `./gradlew build`).



[[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 are greyed out in
the UI, meaning that they 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 or snapshot 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 impact 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].