Skip to content
A quickstart generator for Spring projects
Java Other
  1. Java 99.3%
  2. Other 0.7%
Branch: master
Clone or download
Latest commit d70d832 Sep 17, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.mvn/wrapper Update maven wrapper to Apache Maven 3.6.0 Jan 29, 2019
ci Stop using debug flag for Windows build Aug 25, 2019
eclipse http -> https Aug 18, 2019
initializr-actuator Polish Sep 17, 2019
initializr-bom Extract project generation test utility to dedicated module Aug 21, 2019
initializr-docs Improve custom project request arrangement Aug 29, 2019
initializr-generator-spring Add support for ApplicationContextRunner in ProjectAssetTester Sep 17, 2019
initializr-generator-test Add support for ApplicationContextRunner in ProjectAssetTester Sep 17, 2019
initializr-generator Harmonize Maven build to use containers Sep 4, 2019
initializr-metadata Add a way to easily create a Spring Boot starter from id Aug 21, 2019
initializr-parent Upgrade to Spring Boot 2.1.8 Sep 8, 2019
initializr-service-sample http -> https Aug 18, 2019
initializr-version-resolver Harmonize logging test configuration Aug 18, 2019
initializr-web Polish Sep 17, 2019
src/checkstyle Add JUnit5 checkstyle rule Aug 18, 2019
.cfignore Update for 0.5.0.M1 Aug 4, 2013
.gitattributes Upgrade to Gradle 2.12 Apr 5, 2016
.gitignore Switch project structure to use the new generator Feb 8, 2019
CODE_OF_CONDUCT.adoc http -> https Aug 18, 2019
CONTRIBUTING.adoc http -> https Aug 18, 2019
LICENSE.txt http -> https Aug 18, 2019
README.adoc Polish Aug 18, 2019
mvnw Upgrade to spring-javaformat 0.0.7 Mar 20, 2019
mvnw.cmd Upgrade to spring-javaformat 0.0.7 Mar 20, 2019
pom.xml Extract project generation test utility to dedicated module Aug 21, 2019

README.adoc

Spring Initializr Build Status initializr

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.

  • Git integration.

  • Various low-level 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 https://start.spring.io. To better understand how our service is configured, you may want to check the companion project and, in particular, the configuration of our instance. Such configuration is also described in details in the documentation.

Note
Check the milestones page for an overview of the changes.

Installation and Getting Started

The reference documentation is available in 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-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 for an arbitrary BOM.

  • initializr-web: web endpoints for third party clients.

Supported interfaces

Spring Initializr can be used as follows:

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.

$ 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.

  • 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.

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

$ 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.

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:

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

$ 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 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.

Note
Spring Initializr is not available on Maven central yet so you will have to either build it from source if you want the latest state or use the latest release that is available on https://repo.spring.io/release.

If you want to run our instance at https://start.spring.io, refer to run the default instance locally.

Building from Source

You need Java 1.8 and a bash-like shell.

Building

Invoke the build at the root of the project:

$ ./mvnw clean install

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

$ ./mvnw clean install -Pfull

License

Spring Initializr is Open Source software released under the Apache 2.0 license.

You can’t perform that action at this time.