mirror of
https://gitee.com/dcren/initializr.git
synced 2025-11-28 09:22:41 +08:00
Polish doc
This commit is contained in:
Stephane Nicoll
@@ -117,7 +117,7 @@ versions.
|
||||
|
||||
If that's not what you want, you need to override the `InitializrMetadataProvider` bean to
|
||||
provide your own metadata for the service. For instance, you could swap to an
|
||||
implementation that always returns the contents of your configuration file:
|
||||
implementation that always returns the contents of static `application.yml`:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
@@ -150,8 +150,8 @@ By default, Spring Initializr exposes the following resources (all accessed via
|
||||
* `/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:
|
||||
Each type also defines one or more *tags* that provides 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
|
||||
@@ -264,7 +264,7 @@ If no BOM is available you can specify a version directly:
|
||||
----
|
||||
|
||||
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
|
||||
entry; generating a maven project with it should add the following to the pom:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim"]
|
||||
----
|
||||
@@ -278,40 +278,129 @@ entry; generating a maven project with it should add the following to the pom
|
||||
The rest of this section will detail the other configuration options.
|
||||
|
||||
|
||||
|
||||
[[dependencies-version-range]]
|
||||
==== Availability (version range)
|
||||
|
||||
A dependency can have a `versionRange`, which is a range of versions of Spring Boot which
|
||||
are valid in combination with it. The versions are *not* applied to the dependency itself,
|
||||
but rather used to filter out the dependency, or modify it, when different versions of
|
||||
Spring Boot are selected for the generated project.
|
||||
By default, a dependency is available regardless of the Spring Boot version you have
|
||||
selected. If you need to restrict a dependency to a certain Spring Boot generation you
|
||||
can add a `versionRange` attribute to its definition. A version range is a range of
|
||||
versions of Spring Boot which are valid in combination with it. The versions are *not*
|
||||
applied to the dependency itself, but rather used to filter out the dependency, or modify
|
||||
it, when different versions of Spring Boot are selected for the generated project.
|
||||
|
||||
A version range has a lower and an upper bound, and if the bound is inclusive it is
|
||||
denoted as a square bracket ("[" or "]"), otherwise it is exclusive and denoted by a
|
||||
parenthesis ("(" or ")"). Example: "[1.1.6.RELEASE,1.3.0.M1)" means from all versions from
|
||||
1.1.6 up to but not including 1.3.0.M1 (no not including any of the 1.3.x line.
|
||||
denoted as a square bracket (`[` or `]`), otherwise it is exclusive and denoted by a
|
||||
parenthesis (`(` or `)`). For instance `[1.1.6.RELEASE,1.3.0.M1)` means from all versions
|
||||
from `1.1.6.RELEASE` up to but not including `1.3.0.M1` (concretely no including the
|
||||
`1.3.x` line and after).
|
||||
|
||||
A version range can be a single value, e.g. "1.2.0.RELEASE", which is short for "this
|
||||
A version range can be a single value, e.g. `1.2.0.RELEASE`, which is short for "this
|
||||
version or greater". It is an inclusive lower bound with an implied infinite upper bound.
|
||||
|
||||
The other shorthand notation that is available is to use "x" for the micro-version label,
|
||||
e.g. "1.3.x" means all versions beginning with "1.3". This is mainly used in inclusive
|
||||
bounds, like "[1.2.0.RELEASE,1.4.x.RELEASE)" for "all versions in 1.2.x and 1.3.x but not
|
||||
1.4.0 or above".
|
||||
If you need to specify "the latest release" in a given line, you can use a `x` rather than
|
||||
an hard-coded version. For instance, `1.4.x.BUILD-SNAPSHOT` is the latest snapshot build
|
||||
of the 1.4.x line. For instance, if you want to restrict a dependency from `1.1.0.RELEASE`
|
||||
to the latest stable release of the 1.3.x line, you'd use `[1.1.0.RELEASE,1.3.x.RELEASE]`.
|
||||
|
||||
Snapshots are naturally ordered higher than released versions, so if you are looking to
|
||||
match a dependency to only the latest snapshots of Spring Boot, you could use a version
|
||||
range of "1.5.x.BUILD-SNAPSHOT" (assuming 1.5 was the latest).
|
||||
range of `1.5.x.BUILD-SNAPSHOT` (assuming 1.5 was the latest).
|
||||
|
||||
Remember to quote the values of a version range in YAML configuration files (with double
|
||||
quotes "").
|
||||
TIP: Remember to quote the values of a version range in YAML configuration files (with
|
||||
double quotes "").
|
||||
|
||||
See below in the section on <<howto-link-boot-version,linking versions>> for more examples
|
||||
and idioms.
|
||||
|
||||
|
||||
|
||||
[[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 reference to a repository. A repository is
|
||||
declared at the top level (under `env`) and given an id via the key in the configuration:
|
||||
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
initializr:
|
||||
env:
|
||||
repositories:
|
||||
my-api-repo-1:
|
||||
name: repo1
|
||||
url: http://example.com/repo1
|
||||
----
|
||||
|
||||
Once defined, the repository can then be referred back to in a dependency
|
||||
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
initializr:
|
||||
dependencies:
|
||||
- name: Other
|
||||
content:
|
||||
- name: Foo
|
||||
groupId: org.acme
|
||||
artifactId: foo
|
||||
version: 1.3.5
|
||||
repository: my-api-repo-1
|
||||
----
|
||||
|
||||
It is usually preferable to have a BOM for every dependency, and attach the repository to
|
||||
the BOM instead.
|
||||
|
||||
TIP: The snapshots and milestones repositories on `repo.spring.io` are automatically
|
||||
available with the `spring-snapshots` and `spring-milestones` identifiers respectively.
|
||||
|
||||
|
||||
|
||||
[[create-instance-boms]]
|
||||
=== Configuring Bill of Materials
|
||||
A Bill of Materials (BOM) is a special `pom.xml`, deployed to a Maven repository, and used
|
||||
to control dependency management for a set of related artifacts. In the Spring Boot
|
||||
ecosystem we usually use the suffix `-dependencies` on the artifact id of a BOM. In other
|
||||
projects we see `-bom`. It is recommended that all dependencies are included in a BOM of
|
||||
some sort, since they provide nice high level features for users of the dependency. It is
|
||||
also important that 2 BOMs used in a project do not contain conflicting versions for the
|
||||
same dependency, so the best practice is to look at the existing BOMs in the Initializr
|
||||
before you add a new one, and make sure that you aren't adding a conflict.
|
||||
|
||||
In the Initializr a BOM is declared at the `env` level, and given an id through the
|
||||
configuration key. Example:
|
||||
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
initializr:
|
||||
env:
|
||||
boms:
|
||||
my-api-bom:
|
||||
groupId: org.acme
|
||||
artifactId: my-api-dependencies
|
||||
version: 1.0.0.RELEASE
|
||||
repositories: my-api-repo-1
|
||||
----
|
||||
|
||||
If a BOM requires a special, non-default repository, then it can be referred to here,
|
||||
instead of having to explicitly list the repository again for each dependency. A
|
||||
dependency, or a dependency group, can declare that it requires the use of one or more
|
||||
BOMs by referring to the id:
|
||||
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
initializr:
|
||||
dependencies:
|
||||
- name: Other
|
||||
content:
|
||||
- name: My API
|
||||
id : my-api
|
||||
groupId: org.acme
|
||||
artifactId: my-api
|
||||
bom: my-api-bom
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[dependencies-mappings]]
|
||||
==== Map coordinates according to the Spring Boot version
|
||||
|
||||
In addition to a Spring Boot version range for the dependency or a BOM, you can configure
|
||||
the version relationships at a finer grained level using version mappings. A dependency or
|
||||
BOM has a list of "mappings", each of which consists of a version range, and a set of one
|
||||
@@ -327,37 +416,40 @@ initializr:
|
||||
env:
|
||||
boms:
|
||||
cloud-bom:
|
||||
groupId: org.springframework.cloud
|
||||
artifactId: spring-cloud-dependencies
|
||||
order: 50
|
||||
groupId: com.example.foo
|
||||
artifactId: acme-foo-dependencies
|
||||
mappings:
|
||||
- versionRange: "[1.2.3.RELEASE,1.3.0.RELEASE)"
|
||||
version: Angel.SR6
|
||||
version: Arcturus.SR6
|
||||
- versionRange: "[1.3.0.RELEASE,1.4.0.RELEASE)"
|
||||
version: Brixton.SR7
|
||||
version: Botein.SR7
|
||||
- versionRange: "[1.4.0.RELEASE,1.5.x.RELEASE)"
|
||||
version: Camden.SR6
|
||||
version: Castor.SR6
|
||||
- versionRange: "[1.5.0.RELEASE,1.5.x.BUILD-SNAPSHOT)"
|
||||
version: Dalston.RC1
|
||||
version: Diadem.RC1
|
||||
repositories: spring-milestones
|
||||
- versionRange: "1.5.x.BUILD-SNAPSHOT"
|
||||
version: Dalston.BUILD-SNAPSHOT
|
||||
version: Diadem.BUILD-SNAPSHOT
|
||||
repositories: spring-snapshots,spring-milestones
|
||||
----
|
||||
|
||||
The primary use case here is to map Spring Boot versions to the preferred or supported
|
||||
versions of Spring Cloud. You can also see that for the milestone and snapshot BOMs,
|
||||
versions of the Foo project. You can also see that for the milestone and snapshot BOMs,
|
||||
additional repositories are declared because those artifacts are not in the default
|
||||
repository.
|
||||
|
||||
TIP: We also use the `x` trick in version ranges to avoid updating the range every time
|
||||
a new Spring Boot 1.5 bug fix release is available
|
||||
|
||||
See below in the section on <<howto-link-boot-version,linking versions>> for more examples.
|
||||
|
||||
|
||||
|
||||
[[dependencies-alias]]
|
||||
==== Aliases
|
||||
|
||||
A dependency has an id (e.g. "web-services"), but it can also be referred to using
|
||||
aliases, if those are declared in the metadata. Aliases and ids for dependencies must be
|
||||
globally unique (this is not enforced by the software). For example:
|
||||
A dependency has an id (e.g. "web-services"), but it could be necessary to provide a new
|
||||
id and still be able to serve request from client using the now deprecated id. To do so,
|
||||
an alias can be defined for ths dependency;
|
||||
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
@@ -374,222 +466,183 @@ initializr:
|
||||
The same project can now be generated with `dependencies=ws` or
|
||||
`dependencies=web-services`.
|
||||
|
||||
[[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-repository,reference to a
|
||||
repository>>. A repository is declared at the top level (under `env`) and given an id via
|
||||
the key in the configuration. Example
|
||||
|
||||
[source,yml,indent=0,subs="verbatim,attributes"]
|
||||
----
|
||||
initializr:
|
||||
env:
|
||||
repositories:
|
||||
my-api-repo-1:
|
||||
name: repo1
|
||||
url: http://example.com/repo1
|
||||
----
|
||||
|
||||
he repository can then be referred back to in a dependency
|
||||
|
||||
[source,yml,subs="verbatim,attributes"]
|
||||
----
|
||||
initializr:
|
||||
dependencies:
|
||||
- name: Other
|
||||
content:
|
||||
- name: Foo
|
||||
groupId: org.acme
|
||||
artifactId: foo
|
||||
version: 1.3.5
|
||||
repository: my-api-repo-1
|
||||
----
|
||||
|
||||
It is usually preferable to have a BOM for every dependency, and attach the repository to
|
||||
the BOM instead.
|
||||
|
||||
[[create-instance-boms]]
|
||||
=== Configuring Bill of Materials
|
||||
|
||||
A Bill of Materials (BOM) is a special `pom.xml`, deployed to a Maven repository, and use
|
||||
to control dependency management for a set of related artifacts. In the Spring Boot
|
||||
ecosystem we usually use the suffix "-dependencies" on the artifact id of a BOM. In other
|
||||
projects we see "-bom". It is recommended that all dependencies are included in a BOM of
|
||||
some sort, since they provide nice high level features for users of the dependency. It is
|
||||
also important that 2 BOMs used in a project do not contain conflicting versions for the
|
||||
same dependency, so the best practice is to look at the existing BOMs in the Initializr
|
||||
before you add a new one, and make sure that you aren't adding a conflict. Maven (3.5)
|
||||
will report conflicts when it builds a project containing the two BOMs, even if the
|
||||
dependency that conflicts is not used.
|
||||
|
||||
In the Initializr a BOM is declared at the `env` level, and given an id through the
|
||||
configuration key. Example:
|
||||
|
||||
[source,yml,subs="verbatim,attributes"]
|
||||
----
|
||||
initializr:
|
||||
env:
|
||||
boms:
|
||||
my-api-bom:
|
||||
groupId: org.acme
|
||||
artifactId: my-api-dependencies
|
||||
version: 1.0.0.RELEASE
|
||||
repositories: my-api-repo-1
|
||||
----
|
||||
|
||||
If a BOM requires a special, non-default repository, then it can be referred to here,
|
||||
instead of having to explicitly list the repository again for each dependency. A
|
||||
dependency, or a dependency group, can declare that it requires the use of one or more BOMs by referring to the id. Example:
|
||||
|
||||
[source,yml,subs="verbatim,attributes"]
|
||||
----
|
||||
initializr:
|
||||
dependencies:
|
||||
- name: Other
|
||||
content:
|
||||
- name: My API
|
||||
id : my-api
|
||||
groupId: org.acme
|
||||
artifactId: my-api
|
||||
bom: my-api-bom
|
||||
----
|
||||
|
||||
[[dependencies-facet]]
|
||||
==== Facets
|
||||
|
||||
A "facet" is a label on a dependency which is used to drive a code modification in the
|
||||
generated project. In the standard Initializr generator, there is only one facet that is
|
||||
actually used ("web"), but custom installations might choose to use it for their own
|
||||
purposes. The "web" facet is used to drive the inclusion of `spring-boot-starter-web` if
|
||||
actually used (`web`), but custom installations might choose to use it for their own
|
||||
purposes. The `web` facet is used to drive the inclusion of `spring-boot-starter-web` if
|
||||
any other dependency with that facet is included. The value of the "facets" property of a
|
||||
dependency is a list of strings.
|
||||
|
||||
|
||||
|
||||
[[create-instance-dependencies-link]]
|
||||
==== Links
|
||||
|
||||
Links can be used to provide descriptive and hyperlink data to guide to user on how to
|
||||
learn more about a dependency. A dependency has a "links" property which is a list of
|
||||
`Link`. Each link has a "rel" label to identify it, an "href" and an optional (but
|
||||
recommended) description. In the web UI the links are not currently rendered.
|
||||
`Link`. Each link has a `rel` label to identify it, an `href` and an optional (but
|
||||
recommended) `description`.
|
||||
|
||||
The following `rel` value are currently officially supported:
|
||||
|
||||
* `guide`: the link points to a guide describing how to use the related dependency. It
|
||||
can be a tutorial, a how-to or typically a guide available on https://spring.io/guides
|
||||
* reference: the link points to a section of a developer guide typically or any page that
|
||||
documents how to use the dependency
|
||||
|
||||
The url can be templated if its actual value can change according to the environment. An
|
||||
URL parameter is specified with curly braces, something like
|
||||
`https://example.com/doc/{bootVersion}/section` defines a `bootVersion` parameter.
|
||||
|
||||
The following attributes are currently supported:
|
||||
|
||||
* `bootVersion`: the Spring Boot version that is currently active
|
||||
|
||||
Here is an example that adds two links to the `acme` dependency:
|
||||
|
||||
[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
|
||||
links:
|
||||
- rel: guide
|
||||
href: https://com.example/guides/acme/
|
||||
description: Getting started with Acme
|
||||
- rel: reference
|
||||
href: http://docs.example.com/acme/html
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[create-instance-dependencies-search]]
|
||||
==== Improve search results
|
||||
|
||||
Each dependency can have a "weight" (a number >=0) and also "keywords" (list of string)
|
||||
Each dependency can have a `weight` (a number >=0) and also `keywords` (list of string)
|
||||
that are used to prioritize them in the search feature in the web UI. If you type one of
|
||||
the keywords into the "Dependencies" box in the UI, those dependencies will be listed
|
||||
below, in order of decreasing weight, if they have one (unweighted dependencies come
|
||||
last).
|
||||
|
||||
|
||||
|
||||
[[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-add-a-new-checkbox]]
|
||||
=== Add a new dependency checkbox
|
||||
|
||||
To add a new checkbox, first identify the Maven co-ordinates of the dependency you want to
|
||||
add (`groupId:artifactId:version`) and then check which versions of Spring Boot it works
|
||||
|
||||
[[howto-add-a-new-dependency]]
|
||||
=== Add a new dependency
|
||||
To add a new dependency, first identify the Maven co-ordinates of the dependency you want
|
||||
to add (`groupId:artifactId:version`) and then check which versions of Spring Boot it works
|
||||
with. If there are multiple versions that work with different versions of Spring Boot,
|
||||
then that's fine too.
|
||||
|
||||
* If there is a published BOM that manages the version of you dependency, then add that
|
||||
first, in the `env` section (see the <<create-instance-boms>> section above).
|
||||
|
||||
first, in the `env` section (see <<create-instance-boms>>).
|
||||
* Then configure the dependency, fitting it into an existing group if you can, otherwise
|
||||
creating a new group.
|
||||
|
||||
* If there is a BOM then omit the version.
|
||||
|
||||
* If there is a Spring Boot version range (or min or max) that you need for this
|
||||
dependency, add that as a <<howto-link-boot-version,linked version>>.
|
||||
|
||||
|
||||
|
||||
[[howto-override-a-version]]
|
||||
=== Override the version of a dependency
|
||||
|
||||
Sometimes it happens that the BOM that normally manages your dependency version is in
|
||||
conflict with the newest version. Or maybe this is the case for only a range of Spring
|
||||
Boot versions. Or maybe there just is no BOM, or it's not worth creating one for just one
|
||||
dependency. In these cases you can specify the version manually for a dependency either at the top level, or in a <<howto-link-boot-version,version mapping>>. At the top level it looks like this (just a "version" property in a dependency):
|
||||
dependency. In these cases you can specify the version manually for a dependency either
|
||||
at the top level, or in a
|
||||
<<howto-link-boot-version,version mapping>>. At the top level it looks like this (just
|
||||
a `version` property in a dependency):
|
||||
|
||||
[source,yml,subs="verbatim,attributes"]
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
initializr:
|
||||
dependencies:
|
||||
- name: I/O
|
||||
content:
|
||||
- name: Activiti
|
||||
id: activiti-basic
|
||||
description: Activiti BPMN workflow engine
|
||||
groupId: org.activiti
|
||||
artifactId: activiti-spring-boot-starter-basic
|
||||
version: 5.21.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
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[howto-link-boot-version]]
|
||||
=== Link a Boot version to a version of your dependency
|
||||
|
||||
If your dependency requires a specific version of Spring Boot, ot different versions of
|
||||
Spring Boot require different versions of your dependency there are a couple of mechanisms
|
||||
to configure that.
|
||||
|
||||
The simplest is to put a "versionRange" in the dependency declaration. This is a range of versions of Spring Boot, not or your dependency. For example:
|
||||
The simplest is to put a `versionRange` in the dependency declaration. This is a range of
|
||||
versions of Spring Boot, not of your dependency. For example:
|
||||
|
||||
[source,yml,subs="verbatim,attributes"]
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
initializr:
|
||||
dependencies:
|
||||
- name: Stuff
|
||||
content:
|
||||
- name: Atomikos (JTA)
|
||||
id: jta-atomikos
|
||||
description: JTA distributed transactions via Atomikos
|
||||
- name: Foo
|
||||
id: foo
|
||||
...
|
||||
versionRange: 1.2.0.M1
|
||||
- name: Stormpath
|
||||
id: stormpath
|
||||
groupId: com.stormpath.spring
|
||||
artifactId: stormpath-default-spring-boot-starter
|
||||
- name: Bar
|
||||
id: bar
|
||||
...
|
||||
versionRange: "[1.5.0.RC1,2.0.0.M1)"
|
||||
bom: stormpath-bom
|
||||
----
|
||||
|
||||
In this example Atomikos is available for Spring Boot 1.2.0 (or any milestone of 1.2.0) or
|
||||
greater, and Stormpath is available for Spring Boot 1.5.0 up to, but not including 2.0.0.
|
||||
In this example `Foo` is available for Spring Boot 1.2.0 (or any milestone of 1.2.0) or
|
||||
greater, and `Bar` is available for Spring Boot 1.5.0 up to, but not including 2.0.0.
|
||||
|
||||
If different versions of your dependency work with different versions of Spring Boot,
|
||||
that's when you need the "mappings" property. A mapping is a combination of a `versionRange`
|
||||
(for Spring Boot) and some or all of the other properties of the dependency, overriding
|
||||
that's when you need the `mappings` property. A mapping is a combination of a
|
||||
`versionRange` and some or all of the other properties of the dependency, overriding
|
||||
the values defined at the top level. For example:
|
||||
|
||||
[source,yml,subs="verbatim,attributes"]
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
initializr:
|
||||
dependencies:
|
||||
- name: Stuff
|
||||
content:
|
||||
- name: Cloud Task
|
||||
id: cloud-task
|
||||
groupId: org.springframework.cloud
|
||||
artifactId: spring-cloud-starter-task
|
||||
- name: Foo
|
||||
id: foo
|
||||
groupId: org.acme.foo
|
||||
artifactId: foo-spring-boot-starter
|
||||
versionRange: 1.3.0.RELEASE
|
||||
bom: cloud-task-bom
|
||||
mappings:
|
||||
- versionRange: "[1.3.0.RELEASE,1.3.x.RELEASE]"
|
||||
artifactId: spring-cloud-task-starter
|
||||
artifactId: foo-starter
|
||||
- versionRange: "1.4.0.RELEASE"
|
||||
----
|
||||
|
||||
This dependency is available only for Spring Boot 1.3.0 and above, but up to 1.4.0
|
||||
(i.e. for 1.3.x only) its `artifactId` was actually different.
|
||||
In this example, The artifact of `foo` was changed to `foo-spring-boot-starter` as of the
|
||||
version that is compatible with Spring Boot 1.4. This mapping instruct that if Spring Boot
|
||||
1.3.x is selected, the artifact Id should be set to `foo-starter`.
|
||||
|
||||
A mapping can also be applied to a BOM declaration. For example:
|
||||
|
||||
[source,yml,subs="verbatim,attributes"]
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
initializr:
|
||||
env:
|
||||
@@ -611,46 +664,63 @@ In this example Spring Boot versions up to 1.1.6 select version 1.0.0 of the BOM
|
||||
a different repository. Spring Boot versions 1.2.1 and above select 2.0.0 of the BOM and
|
||||
yet another repository.
|
||||
|
||||
|
||||
|
||||
[[howto-add-snapshot-repository]]
|
||||
=== Configure a snapshot repository
|
||||
|
||||
A dependency, or a BOM, might require the use of a specific repository, if the default one
|
||||
(usually Maven Central) does not contain the artifacts. Normally, the best place to
|
||||
declare that is in the BOM configuration, but if there isn't a BOM then you can put it in
|
||||
the dependency itself. You can also use a Spring Boot <<You can declare a
|
||||
repository,version mapping>> to override the default repository for a dependency or BOM.
|
||||
|
||||
|
||||
|
||||
[[howto-dependency-starter-flag]]
|
||||
=== Make sure a regular dependency brings the base starter
|
||||
|
||||
If a dependency does not stand on its own (and specifically if it does not depend on an
|
||||
existing Spring Boot starter) you can flag it as "starter=false". When a project is
|
||||
generated that only has dependencies with this flag set, then a Spring Boot starter is
|
||||
added as well (the vanilla `spring-boot-starter` or the `spring-boot-starter-web` if there
|
||||
is a dependency with the web facet).
|
||||
existing Spring Boot starter) you can flag it as a "non starter":
|
||||
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
initializr:
|
||||
dependencies:
|
||||
- name: Stuff
|
||||
content:
|
||||
- name: Lib
|
||||
id: lib
|
||||
groupId: com.acme
|
||||
artifactId: lib
|
||||
starter:false
|
||||
----
|
||||
|
||||
When a project is generated that only has dependencies with this flag set, then the base
|
||||
Spring Boot starter is added as well.
|
||||
|
||||
|
||||
|
||||
[[howto-group-share-settings]]
|
||||
=== Share common dependency settings in a group
|
||||
|
||||
A dependency group is a hint for user interface implememtations, to group things together
|
||||
A dependency group is a hint for user interface implementations, to group things together
|
||||
for users when they are selecting dependencies. It is also a convenient way to share
|
||||
settings between dependencies because every dependency inherits all the settings. The most
|
||||
common settings in a group are the group id, version range (for Spring Boot versions), and
|
||||
bom. Example:
|
||||
common settings in a group are the `groupId`, `versionRange` and `bom`:
|
||||
|
||||
[source,yml,subs="verbatim,attributes"]
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
initializr:
|
||||
dependencies:
|
||||
- name: Stuff
|
||||
bom: stuff-bom
|
||||
versionRange: "[1.3.0.RELEASE,2.0.x)"
|
||||
versionRange: "[1.3.0.RELEASE,2.0.0.M1)"
|
||||
content:
|
||||
...
|
||||
----
|
||||
|
||||
These dependencies, by default, will be available only for Spring Boot versions 1.3 to
|
||||
2.0, and will bring in a BOM already declared as "stuff-bom" in the `env` section.
|
||||
These dependencies, by default, will be available only for Spring Boot versions 1.3 up to
|
||||
2.0 (excluded) and will bring in the `stuff-bom` BOM.
|
||||
|
||||
|
||||
|
||||
[[create-instance-advanced-config]]
|
||||
== Advanced configuration
|
||||
|
||||
@@ -3,8 +3,8 @@
|
||||
|
||||
[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
|
||||
This section provides a brief overview of the 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.
|
||||
--
|
||||
|
||||
@@ -21,18 +21,17 @@ You can easily create your own instance of the Initializr, by using the jars as
|
||||
in your own app. 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. If that
|
||||
sounds interesting, then the <<configuration-guide.adoc#configuration-guide>> section has
|
||||
all the details you need. You might only want to modify an existing instance of the
|
||||
Initializr, e.g. to add a new dependency type, or update the version of an existing
|
||||
one. For those and other simple and common use cases check out the
|
||||
<<configuration-guide.adoc#configuration-howto>> section.
|
||||
sounds interesting, then <<configuration-guide.adoc#configuration-guide>> has all the
|
||||
details you need. You might only want to modify an existing instance of the Initializr,
|
||||
e.g. to add a new dependency type, or update the version of an existing
|
||||
one. For those and other simple and common use cases check out
|
||||
<<configuration-guide.adoc#configuration-howto>>.
|
||||
|
||||
The Initializr also provides an extensible API to generate quickstart projects, and to
|
||||
inspect the metadata used to generate projects, for instance to list the available
|
||||
dependencies and versions. The API can be used standalone or embedded in other tools
|
||||
(e.g. it is used in Spring Tool Suite, and in the IntelliJ and Netbeans plugins for Spring
|
||||
Boot). These features are covered in a separate <<api-guide.adoc#api-guide>> section of
|
||||
this document.
|
||||
(e.g. it is used in Spring Tool Suite, and in the IntelliJ IDEA and Netbeans plugins for
|
||||
Spring Boot). These features are covered in <<api-guide.adoc#api-guide>>.
|
||||
|
||||
[[initializr-documentation-about]]
|
||||
== About the documentation
|
||||
|
||||
@@ -139,11 +139,23 @@ 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.
|
||||
The following attributes are supported:
|
||||
|
||||
* Programming language: `language` (`java`, `groovy` or `kotlin`)
|
||||
* Java version: `javaVersion` (`1.6`, `1.7`, `1.8`)
|
||||
* Project type: `type` (`maven-project`, `gradle-project`)
|
||||
* Packaging: `packaging` (`jar`, `war`)
|
||||
* Group: `groupId`
|
||||
* Artifact: `artifact`
|
||||
* Name: `name`
|
||||
* Description: `description`
|
||||
* Package Name: `packageName`
|
||||
|
||||
TIP: The same default rules will apply if a property is overridden. For instance, if the
|
||||
Group is customized, it will automatically customize the root package as well.
|
||||
|
||||
NOTE: The Spring Boot version and the list of dependencies cannot be customized that way
|
||||
as they evolve quite frequently.
|
||||
|
||||
[[command-line]]
|
||||
== Command line support
|
||||
@@ -152,7 +164,7 @@ available options of a particular instance, simply "curl it", i.e. if you have `
|
||||
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
|
||||
The result is 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,
|
||||
@@ -211,9 +223,10 @@ Spring Initializr is also integrated in all major Java IDEs and allows you to cr
|
||||
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
|
||||
* NetBeans (using the http://plugins.netbeans.org/plugin/67888/nb-springboot[NB SpringBoot plugin])
|
||||
|
||||
Refer to the documentation of your favorite IDE for more details.
|
||||
|
||||
|
||||
@@ -73,7 +73,7 @@ The wiremock fetaures come with Spring Cloud Contract Wiremock:
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
---
|
||||
----
|
||||
|
||||
=== Using the Stub Runner
|
||||
|
||||
@@ -104,7 +104,7 @@ stubs declared as a dependency):
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
---
|
||||
----
|
||||
|
||||
|
||||
[source,java,indent=0]
|
||||
|
||||
Reference in New Issue
Block a user