The Spring Initializr reference guide is available as html, pdf and epub documents. The latest copy is available at docs.spring.io/initializr/docs/current/reference.

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

Having trouble with Spring Initializr, We’d like to help!

	Note
	All of Spring Initializr is open source, including the documentation! If you find problems with the docs; or if you just want to improve them, please get involved.

Any third party client can retrieve the capabilities of the service by issuing a GET on the root URL using the following Accept header: application/vnd.initializr.v2.1+json. Please note that the metadata may evolve in a non backward compatible way in the future so adding this header ensures the service returns the metadata format you expect.

This is an example output for a service running at start.spring.io:

request. 

GET / HTTP/1.1
Accept: application/vnd.initializr.v2.1+json
Host: start.spring.io

response. 

HTTP/1.1 200 OK
ETag: "1262473f5c28f970e1e42d107213b064"
Content-Type: application/vnd.initializr.v2.1+json
Cache-Control: max-age=604800
Content-Length: 4872

{
  "_links" : {
    "maven-build" : {
      "href" : "https://start.spring.io/pom.xml?type=maven-build{&dependencies,packaging,javaVersion,language,bootVersion,groupId,artifactId,version,name,description,packageName}",
      "templated" : true
    },
    "maven-project" : {
      "href" : "https://start.spring.io/starter.zip?type=maven-project{&dependencies,packaging,javaVersion,language,bootVersion,groupId,artifactId,version,name,description,packageName}",
      "templated" : true
    },
    "gradle-build" : {
      "href" : "https://start.spring.io/build.gradle?type=gradle-build{&dependencies,packaging,javaVersion,language,bootVersion,groupId,artifactId,version,name,description,packageName}",
      "templated" : true
    },
    "gradle-project" : {
      "href" : "https://start.spring.io/starter.zip?type=gradle-project{&dependencies,packaging,javaVersion,language,bootVersion,groupId,artifactId,version,name,description,packageName}",
      "templated" : true
    },
    "dependencies" : {
      "href" : "https://start.spring.io/dependencies{?bootVersion}",
      "templated" : true
    }
  },
  "dependencies" : {
    "type" : "hierarchical-multi-select",
    "values" : [ {
      "name" : "Core",
      "values" : [ {
        "id" : "web",
        "name" : "Web",
        "description" : "Web dependency description",
        "_links" : {
          "guide" : {
            "href" : "https://example.com/guide",
            "title" : "Building a RESTful Web Service"
          },
          "reference" : {
            "href" : "https://example.com/doc"
          }
        }
      }, {
        "id" : "security",
        "name" : "Security"
      }, {
        "id" : "data-jpa",
        "name" : "Data JPA"
      } ]
    }, {
      "name" : "Other",
      "values" : [ {
        "id" : "org.acme:foo",
        "name" : "Foo",
        "_links" : {
          "guide" : [ {
            "href" : "https://example.com/guide1"
          }, {
            "href" : "https://example.com/guide2",
            "title" : "Some guide for foo"
          } ],
          "reference" : {
            "href" : "https://example.com/{bootVersion}/doc",
            "templated" : true
          }
        }
      }, {
        "id" : "org.acme:bar",
        "name" : "Bar"
      }, {
        "id" : "org.acme:biz",
        "name" : "Biz",
        "versionRange" : "1.2.0.BUILD-SNAPSHOT"
      }, {
        "id" : "org.acme:bur",
        "name" : "Bur",
        "versionRange" : "[1.1.4.RELEASE,1.2.0.BUILD-SNAPSHOT)"
      }, {
        "id" : "my-api",
        "name" : "My API"
      } ]
    } ]
  },
  "type" : {
    "type" : "action",
    "default" : "maven-project",
    "values" : [ {
      "id" : "maven-build",
      "name" : "Maven POM",
      "action" : "/pom.xml",
      "tags" : {
        "build" : "maven",
        "format" : "build"
      }
    }, {
      "id" : "maven-project",
      "name" : "Maven Project",
      "action" : "/starter.zip",
      "tags" : {
        "build" : "maven",
        "format" : "project"
      }
    }, {
      "id" : "gradle-build",
      "name" : "Gradle Config",
      "action" : "/build.gradle",
      "tags" : {
        "build" : "gradle",
        "format" : "build"
      }
    }, {
      "id" : "gradle-project",
      "name" : "Gradle Project",
      "action" : "/starter.zip",
      "tags" : {
        "build" : "gradle",
        "format" : "project"
      }
    } ]
  },
  "packaging" : {
    "type" : "single-select",
    "default" : "jar",
    "values" : [ {
      "id" : "jar",
      "name" : "Jar"
    }, {
      "id" : "war",
      "name" : "War"
    } ]
  },
  "javaVersion" : {
    "type" : "single-select",
    "default" : "1.8",
    "values" : [ {
      "id" : "1.6",
      "name" : "1.6"
    }, {
      "id" : "1.7",
      "name" : "1.7"
    }, {
      "id" : "1.8",
      "name" : "1.8"
    } ]
  },
  "language" : {
    "type" : "single-select",
    "default" : "java",
    "values" : [ {
      "id" : "groovy",
      "name" : "Groovy"
    }, {
      "id" : "java",
      "name" : "Java"
    }, {
      "id" : "kotlin",
      "name" : "Kotlin"
    } ]
  },
  "bootVersion" : {
    "type" : "single-select",
    "default" : "1.1.4.RELEASE",
    "values" : [ {
      "id" : "1.2.0.BUILD-SNAPSHOT",
      "name" : "Latest SNAPSHOT"
    }, {
      "id" : "1.1.4.RELEASE",
      "name" : "1.1.4"
    }, {
      "id" : "1.0.2.RELEASE",
      "name" : "1.0.2"
    } ]
  },
  "groupId" : {
    "type" : "text",
    "default" : "com.example"
  },
  "artifactId" : {
    "type" : "text",
    "default" : "demo"
  },
  "version" : {
    "type" : "text",
    "default" : "0.0.1-SNAPSHOT"
  },
  "name" : {
    "type" : "text",
    "default" : "demo"
  },
  "description" : {
    "type" : "text",
    "default" : "Demo project for Spring Boot"
  },
  "packageName" : {
    "type" : "text",
    "default" : "com.example"
  }
}

The current capabilities are the following:

Each top-level attribute (i.e. capability) has a standard format:

The following attribute type are supported:

Each action is defined as a HAL-compliant URL. For instance, the maven-project type templated URL is defined as follows:

Type link example. 

{
  "href" : "https://start.spring.io/starter.zip?type=maven-project{&dependencies,packaging,javaVersion,language,bootVersion,groupId,artifactId,version,name,description,packageName}",
  "templated" : true
}

You can use Spring HATEOAS and the UriTemplate helper in particular to generate an URI from template variables. Note that the variables match the name of top-level attribute in the metadata document. If you can’t parse such URI, the action attribute of each type gives you the root action to invoke on the server. This requires more manual handling on your end.

{
  "name": "Display name",
  "id": "org.acme.project:project-starter-foo",
  "description": "What starter foo does"
}

{
  "name" : "Core",
  "values" : [ {
    "id" : "web",
    "name" : "Web",
    "description" : "Web dependency description",
    "_links" : {
      "guide" : {
        "href" : "https://example.com/guide",
        "title" : "Building a RESTful Web Service"
      },
      "reference" : {
        "href" : "https://example.com/doc"
      }
    }
  }, {
    "id" : "security",
    "name" : "Security"
  }, {
    "id" : "data-jpa",
    "name" : "Data JPA"
  } ]
}

{
  "id" : "maven-build",
  "name" : "Maven POM",
  "action" : "/pom.xml",
  "tags" : {
    "build" : "maven",
    "format" : "build"
  }
}

{
  "id" : "jar",
  "name" : "Jar"
}

{
  "id" : "1.6",
  "name" : "1.6"
}

{
  "id" : "groovy",
  "name" : "Groovy"
}

{
  "id" : "1.2.0.BUILD-SNAPSHOT",
  "name" : "Latest SNAPSHOT"
}

Each top-level element has a default attribute that should be used as a hint to provide the default value in the relevant UI component.

A convenient way to consume the stubs in your project is to add a test dependency:

<dependency>
    <groupId>io.spring.initializr</groupId>
    <artifactId>initializr-web</artifactId>
    <classifier>stubs</classifier>
    <version>{project-version}</version>
    <scope>test</scope>
</dependency>

and then pull the stubs from the classpath. In a Spring Boot application, using Spring Cloud Contract, you can start a WireMock server and register all the stubs with it like this:

@RunWith(SpringRunner.class)
@SpringBootTest
@AutoConfigureWireMock(port = 0,
    stubs="classpath:META-INF/io.spring.initializr/initializr-web/0.3.0.BUILD-SNAPSHOT")
public class ClientApplicationTests {

	@Value("${wiremock.server.port}")
	private int port;

    ...

}

Alternatively you can configure the stub runner to look for the artifact. The example below will automatically download, if necessary, the latest version of the initializr stubs:

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = WebEnvironment.NONE)
@AutoConfigureStubRunner(
		ids = "io.spring.initializr:initializr-web",
		workOffline = true)
public class InitializrIntegrationTests {

	@Autowired
	private StubFinder stubFinder;

	@Autowired
	private RestTemplate restTemplate;

	@Test
	public void testCurrentMetadata() throws IOException {
		RequestEntity<Void> request = RequestEntity.get(createUri("/"))
				.accept(MediaType.valueOf("application/vnd.initializr.v2.1+json"))
				.build();

		ResponseEntity<String> response = this.restTemplate
				.exchange(request, String.class);
		assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
		// other assertions here
	}

	private URI createUri(String path) {
		String url = this.stubFinder.findStubUrl("initializr-web").toString();
		return URI.create(url + path);
	}

	@TestConfiguration
	static class Config {

		@Bean
		public RestTemplate restTemplate(RestTemplateBuilder builder) {
			return builder.build();
		}

	}

}

	Tip
	If you want to test a specific version or validate your API against multiple versions you can define the version to use in the annotation, something like @AutoConfigureStubRunner( ids = "io.spring.initializr:initializr-web:0.3.0.BUILD-SNAPSHOT", workOffline = true) public class InitializrIntegrationTests { ... }

Then you have a server that returns the stub of the JSON metadata (metadataWithCurrentAcceptHeader.json) when you send it a header Accept:application/vnd.initializr.v2.1+json (as recommended).

The stubs are laid out in a jar file in a form (under "/mappings") that can be consumed by WireMock just by setting its file source. The names of the individual stubs are the same as the method names of the test cases that generated them in the Initializr project. So for example there is a test case "metadataWithV2AcceptHeader" in MainControllerIntegrationTests that makes assertions about the response when the accept header is application/vnd.initializr.v2.1+json. The response is recorded in the stub, and it will match in WireMock if the same headers and request parameters that were used in the Initializr test case and used in the client. The method name usually summarizes what those values are.

	Tip
	Check the code for a full list of the available configuration options.

The env element defines environment option that the service uses:

If some of your dependencies require a custom Bill of Materials (BOM) and/or a custom repository, you can add them here and use the id as a reference. For instance, let’s say that you want to integrate with library foo and it requires a foo-bom and a foo-repo. You can configure things as follows:

initializr:
  env:
    boms:
      foo-bom:
        groupId: com.example
        artifactId: foo-bom
        version: 1.2.3
    repositories:
      foo-repo:
        name: foo-release-repo
        url: https://repo.example.com/foo
        snapshotsEnabled: false

You can then use the foo-bom and foo-repo in a "dependency" or "dependency group" section.

	Note
	The spring-milestones and spring-snapshots repositories are available by default. Please note that these are just references and won’t impact the project unless you choose a dependency that explicitly refer to a bom and/or repo by id. Check the example below for more details.

The dependencies section allows you define a list of groups, each group having one more dependency. A group gather dependencies that share a common characteristics (i.e. all web-related dependencies for instance).

A dependency has the following basic characteristics:

	Tip
	Check the code for a full list of the available configuration options.

Here is the most basic dependency entry you could have

initializr:
  dependencies:
    - name: Core
      content:
        - id: security
          name: Security
          description: Secure your application via spring-security

	Tip
	The security dependency is held within a group called "Core".

This adds an option name Security with a tooltip showing the description above. If a project is generated with that dependency, the org.springframework.boot:spring-boot-starter-security dependency will be added to the project.

Let’s now add a custom dependency that is not managed by Spring Boot and that only work from Spring Boot 1.2.0.RELEASE and onwards but should not be used in the 1.3 lines and further for some reason.

initializr:
  dependencies:
    - name: Core
      content:
        - id: my-lib-id
          name: My lib
          description: Secure your application via spring-security
          groupId: com.example.foo
          artifactId: foo-core
          bom: foo-bom
          repository: foo-repo
          versionRange: "[1.2.0.RELEASE,1.3.0.M1)"

If one selects this entry, the com.example.foo:foo-core} dependency will be added and the Bill of Materials and repository for foo will be added automatically to the project as well (see the "Env section" above for a reference to those identifiers). Because the bom provides a dependency management for foo-core there is no need to hard code the version in the configuration.

The versionRange syntax follows some simple rules: a square bracket "[" or "]" denotes an inclusive end of the range and a round bracket "(" or ")" denotes an exclusive end of the range. A range can also be unbounded by defining a a single version. In the example above, the dependency will be available as from 1.2.0.RELEASE up to, not included, 1.3.0.M1 (which is the first milestone of the 1.3 line).

The other section defines the default and the list of available options in the web UI. This also drives how the meta-data for your instance are generated and tooling support is meant to react to that.

For instance, if you want your groupId to default to org.acme and the javaVersions to only be 1.7 and 1.8 you would write the following config:

initializr:
  groupId:
    value: org.acme
  javaVersions:
    - id: 1.8
      default: true
    - id: 1.7
      default: false