initializr/README.adoc

= Spring Initializr image:https://ci.spring.io/api/v1/teams/initializr/pipelines/initializr/jobs/build/badge["Build Status", link="https://ci.spring.io/teams/initializr/pipelines/initializr?groups=Build"] image:https://badges.gitter.im/spring-io/initializr.svg[link="https://gitter.im/spring-io/initializr?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"]

:boot-doc: https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle
:code: https://github.com/spring-io/initializr/blob/master
:docs: https://docs.spring.io/initializr/docs/current-SNAPSHOT/reference
:service: https://github.com/spring-io/start.spring.io

Spring Initializr provides an extensible API to generate JVM-based projects with
implementations for several common concepts:

* Basic language generation for Java, Kotlin and Groovy.
* Build system abstraction with implementations for Apache Maven and Gradle.
* `.gitignore` support.
* Several hook-points for custom resources generations.

The various options for the projects are expressed in a metadata model that allows you to
configure the list of dependencies, supported JVM and platform versions, etc.

Spring Initializr also exposes web endpoints to generate an actual project and also
serve its metadata in a well-known format to allow third-party clients to provide the
necessary assistance.

A set of optional conventions for Spring Boot projects is provided and are used in our
production instance at link:https://start.spring.io[]. To better understand how our
service is configured, you may want to check {service}[the companion project] and, in
particular, the
{service}/blob/master/start-site/src/main/resources/application.yml[configuration of our
instance]. Such configuration is also described in details in the documentation.

NOTE: While Spring Initializr is now available on Maven Central, it is still in a pre 1.0
state and major refactoring are still possible. Check the
https://github.com/spring-io/initializr/milestones[milestones page] for an overview of the
changes.

== Installation and Getting Started
The reference documentation is available in {docs}/html/[HTML format].


== Modules
Spring Initializr has the following modules:

* `initializr-actuator`: optional module to provide additional information and statistics
on project generation.
* `initializr-bom`: provides a Bill of Materials for easier dependency management in your
project.
* `initializr-docs`: documentation.
* `initializr-generator`: core project generation library.
* `initializr-generator-spring`: optional module defining the conventions for a typical
Spring Boot project. Can be reused or replaced by your own conventions.
* `initializr-generator-test`: test infrastructure for project generation.
* `initializr-metadata`: metadata infrastructure for various aspects of the project.
* `initializr-service-sample`: showcases a basic custom instance.
* `initializr-version-resolver`: optional module to extract version numbers from an
arbitrary POM.
* `initializr-web`: web endpoints for third party clients.

== Supported interfaces
Spring Initializr can be used as follows:

* On the command-line with {boot-doc}/#cli-init[the Spring Boot CLI] or simply with
`cURL` or `HTTPie`.
* In your IDE if you are using STS, IntelliJ IDEA Ultimate, NetBeans (with
https://github.com/AlexFalappa/nb-springboot[this plugin]) or VSCode (with
https://github.com/microsoft/vscode-spring-initializr[the `vscode-spring-initializr`
plugin]).
* With a custom Web UI (check ours at link:https://start.spring.io[]).

There are other command-line integrations out there and you can also build your own!

== Generating a project
As Spring Initializr doesn't come with a Web UI, you can use any of the out-of-the-box
integration to generate a project. For instance, the following `curl` command downloads
a project archive with a Maven-based project and the necessary infrastructure to start
a basic Spring Boot app.

[source,bash]
----
$ curl https://start.spring.io/starter.zip -o demo.zip
----

The project to generate can be customized of course with a number of options:

* Basic information for the generated project: `groupId`, `artifactId`, `version`,
`name`, `description` and `packageName`
** The `name` attribute is also used to generate a default application name. The
logic is that the name of the application is equal to the `name` attribute with an
`Application` suffix (unless said suffix is already present). Of course, if the
specified name contains an invalid character for a java identifier, `Application` is
used as fallback.
** The `artifactId` attribute not only defines the identifier of the project in the
build but also the name of the generated archive.
* `dependencies`: the identifiers of the dependencies to add to the
project. Such identifiers are defined through configuration and are exposed in the
<<metadata,metadata>>.
* `type`: the _kind_ of project to generate (e.g. `maven-project`). Again, each
service exposes an arbitrary number of supported types and these are available in the
<<metadata,metadata>>.
* `javaVersion`: the JVM language level (e.g. `1.8`).
* `bootVersion`: the platform version to use (e.g. `2.1.0.RELEASE`).
* `language`: the programming language to use (e.g. `java`).
* `packaging`: the packaging of the project (e.g. `jar`).
* `applicationName`: the name of the application class (inferred by the `name`
attribute by default).
* `baseDir`: the name of the base directory to create in the archive. By default, the
project is stored in the root.

[TIP]
====
You can "curl" an instance to get a usage page with examples (try
`curl https://start.spring.io`)
====

This command generates an `another-project` directory holding a Gradle web-based
Groovy project using the actuator:

[source,bash]
----
$ curl https://start.spring.io/starter.tgz -d dependencies=web,actuator \
-d language=groovy -d type=gradle-project -d baseDir=another-project | tar -xzvf -
----

NOTE: The `/starter.tgz` endpoint offers the same feature as `/starter.zip` but
generates a compressed tarball instead.

You could use this infrastructure to create your own client since the project is
generated via a plain HTTP call.

[[metadata]]
== Service metadata
The service metadata is used by all clients to know which values they should expose for
the standard attributes of a project. For instance, a custom version can specify that the
default `groupId` is `com.example.acme`. You can grab the metadata on the root endpoint
with the appropriate `Accept` header:

[source,bash]
----
$ curl -H 'Accept: application/json' https://start.spring.io
----

NOTE: As stated above, if you use `curl` without an accept header, you'll retrieve a
human readable text version of the metadata.

`HTTPie` is also supported:

[source,bash]
----
$ http https://start.spring.io Accept:application/json
----

The metadata basically lists the _capabilities_ of the service, that is the available
options for all request parameters (`dependencies`, `type`, `bootVersion`, etc.) A client
to the service uses that information to initialize the select options and the tree of
available dependencies.

The metadata also lists the default values for simple _text_ parameter (i.e. the
default `name` for the project).

NOTE: More details about the structure of the metadata are
{docs}/html/#metadata-format[available in the documentation].

== Running your own instance
You can easily run your own instance. The `initializr-web` modules uses Spring Boot
so when it is added to a project, it will trigger the necessary auto-configuration to
deploy the service.

The `initializr-service-sample` showcases a basic custom instance with dedicated metadata.

If you want to run our instance at https://start.spring.io, refer to
https://github.com/spring-io/start.spring.io#run-app[run the default instance locally].


[[build]]
== Building from Source
You need Java 1.8 and a bash-like shell.

[[building]]
=== Building
Invoke the build at the root of the project:

[indent=0]
----
    $ ./mvnw clean install
----

To generate the docs as well, you should enable the `full` profile:

[indent=0]
----
    $ ./mvnw clean install -Pfull
----

== License
Spring Initializr is Open Source software released under the
https://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license].