lsm/initializr
1
0
Fork 0
mirror of https://gitee.com/dcren/initializr.git synced 2025-04-05 17:38:06 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Use platform version rather than Boot version when applicable

Browse Source 
Although the code still has a reference to `bootVersion` for backward
compatible reason, this commit updates the reference guide to refer to
"platform version".

Closes gh-976
This commit is contained in:
Stephane Nicoll 2020-11-17 14:59:19 +01:00
parent 4291ab97f5
commit d665620a91
2 changed files with 68 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
initializr-docs/src/main/asciidoc/configuration-guide.adoc
View File

@ -279,9 +279,7 @@ projects using the conventions provided by the `initializr-generator-spring` mod
Once you've started the application, you can hit http://localhost:8080. You'll get a json Once you've started the application, you can hit http://localhost:8080. You'll get a json
document that describes the capabilities of the service. None of the select capabilities document that describes the capabilities of the service. None of the select capabilities
will have values (except the one for the Spring Boot version, we will will have values. In the rest of this section, we will configure those basic settings.
<<create-instance-boot-versions,come back to that later>>). In the rest of this section,
we will configure those basic settings.
[TIP] [TIP]
==== ====
@ -362,11 +360,14 @@ defaults can be overridden as shown below:
[[create-instance-boot-versions]] [[create-instance-platform-versions]]
=== Configuring available Spring Boot versions === Configuring available platform versions
You can configure the available Spring Boot versions the same way you configure other You can configure the available platform versions the same way you configure other
capabilities. capabilities.
NOTE: the concept is reference to `bootVersions` as it predates the concept of platform
versions.
[source,yaml,indent=0] [source,yaml,indent=0]
---- ----
initializr: initializr:
@ -383,14 +384,15 @@ capabilities.
---- ----
The configuration above provides three versions, with `2.3.2` being used by default. In The configuration above provides three versions, with `2.3.2` being used by default. In
practice though, you may want to upgrade the available Spring Boot versions without having practice though, you may want to upgrade the available platform versions without having
to redeploy the application every time. Implementing your own to redeploy the application every time. Implementing your own
`InitializrMetadataUpdateStrategy` bean allows you to update the metadata at runtime. `InitializrMetadataUpdateStrategy` bean allows you to update the metadata at runtime.
If you look at https://spring.io/projects/spring-boot[the project home page for Spring If you look at https://spring.io/projects/spring-boot[the project home page for Spring
Boot], the latest versions are displayed. `SaganInitializrMetadataUpdateStrategy` is an Boot], the latest versions are displayed. `SaganInitializrMetadataUpdateStrategy` is an
implementation of that strategy that fetches the latest Spring Boot versions and update implementation of that strategy that fetches the latest Spring Boot versions and update
the metadata to make sure a running instance always get the latest available versions. the metadata to make sure a running instance using those conventions always get the latest
available versions.
If you are behind a proxy, or need to customize the `RestTemplate` that is used behind the If you are behind a proxy, or need to customize the `RestTemplate` that is used behind the
scenes, you can define a `RestTemplateCustomizer` bean in your configuration. For more scenes, you can define a `RestTemplateCustomizer` bean in your configuration. For more
@ -454,7 +456,7 @@ project:
NOTE: If you intend to build a custom client against your service, you can add as many NOTE: If you intend to build a custom client against your service, you can add as many
tags as you want, and process them in the client in a way that makes sense for your users. tags as you want, and process them in the client in a way that makes sense for your users.
For instance, the spring boot CLI uses them as a shortcut to the full type id. So rather For instance, the Spring Boot CLI uses them as a shortcut to the full type id. So rather
than having to create a Gradle project as follows: than having to create a Gradle project as follows:
[indent=0,subs="verbatim,quotes,attributes"] [indent=0,subs="verbatim,quotes,attributes"]
@ -507,10 +509,10 @@ surface area or any other form of grouping. In the example above, a `Web` group
unique dependency. A group can also provide default values for various settings, see the unique dependency. A group can also provide default values for various settings, see the
<<howto-group-share-settings,dedicated how-to>> for more details. <<howto-group-share-settings,dedicated how-to>> for more details.
In our `spring-boot-starter-web` example above, the dependency is _managed_ by Spring In our `spring-boot-starter-web` example above, we assume that the dependency is _managed_
Boot so there is no need to provide a `version` attribute for it. You'll surely need to by the platform so there is no need to provide a `version` attribute for it. You'll surely
define additional dependencies that are not provided by Spring Boot and we strongly need to define additional dependencies that are not provided by the platform and we
recommend you to use a <<create-instance-boms,Bill Of Materials (or BOM)>>. strongly recommend you to use a <<create-instance-boms,Bill Of Materials (or BOM)>>.
If no BOM is available you can specify a version directly: If no BOM is available you can specify a version directly:
@ -546,12 +548,12 @@ The rest of this section will detail the other configuration options.
[[dependencies-compatibility-range]] [[dependencies-compatibility-range]]
==== Compatibility Range ==== Compatibility Range
By default, a dependency is available regardless of the Spring Boot version you have By default, a dependency is available regardless of the platform version you have
selected. If you need to restrict a dependency to a certain Spring Boot generation you selected. If you need to restrict a dependency to a certain platform generation you
can add a `compatibilityRange` attribute to its definition that defines a version range. A can add a `compatibilityRange` attribute to its definition that defines a version range. A
version range is a range of versions of Spring Boot which are valid in combination with version range is a range of versions of the platform which are valid in combination with
it. The versions are *not* applied to the dependency itself, but rather used to filter out 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 the dependency, or modify it, when different versions of the platform are selected for the
generated project. generated project.
A version is composed of four parts: a major revision, a minor revision, a patch A version is composed of four parts: a major revision, a minor revision, a patch
@ -594,13 +596,13 @@ of the 1.4.x line. For instance, if you want to restrict a dependency from `1.1.
to the latest stable release of the 1.3.x line, you'd use `[1.1.0.RELEASE,1.3.x.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 the most recent version of a given line, so if you are looking to Snapshots are naturally the most recent version of a given line, so if you are looking to
match a dependency to only the latest snapshots of Spring Boot, you could use a version match a dependency to only the latest snapshots of the platform, 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).
TIP: Remember to quote the values of a version range in YAML configuration files (with TIP: Remember to quote the values of a version range in YAML configuration files (with
double quotes ""). double quotes "").
See below in the section on <<howto-link-boot-version,linking versions>> for more examples See below in the section on <<howto-link-platform-version,linking versions>> for more examples
and idioms. See also how the <<howto-platform-version-format,platform version format>> can and idioms. See also how the <<howto-platform-version-format,platform version format>> can
be configured. be configured.
@ -692,12 +694,12 @@ BOMs by referring to the id:
[[dependencies-mappings]] [[dependencies-mappings]]
==== Map coordinates according to the Spring Boot version ==== Map coordinates according to the platform version
In addition to a Spring Boot version range for the dependency or a BOM, you can configure In addition to a compatibility range for the dependency or a BOM, you can configure
the version relationships at a finer grained level using version mappings. A dependency or 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 BOM has a list of "mappings", each of which consists of a version range, and a set of one
or more dependency properties to override for those versions of Spring Boot. You can use a or more dependency properties to override for those versions of the platform. You can use
mapping to switch the version of a dependency, or (better) the BOM, or to change its a mapping to switch the version of a dependency, or (better) the BOM, or to change its
artifact id (if the project changed its packaging) for instance. artifact id (if the project changed its packaging) for instance.
Here's an example of a BOM with mappings: Here's an example of a BOM with mappings:
@ -727,16 +729,16 @@ Here's an example of a BOM with mappings:
repositories: spring-snapshots,spring-milestones repositories: spring-snapshots,spring-milestones
---- ----
The primary use case here is to map Spring Boot versions to the preferred or supported The primary use case here is to map platform versions to the preferred or supported
versions of the Foo project. 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 additional repositories are declared because those artifacts are not in the default
repository. Initially the BOM was identified as `com.example.bar:acme-foo-bom` and renamed repository. Initially the BOM was identified as `com.example.bar:acme-foo-bom` and renamed
as of `Botein` to `com.example.foo:acme-foo-dependencies`. as of `Botein` to `com.example.foo:acme-foo-dependencies`.
TIP: We also use the `x` trick in version ranges to avoid updating the range every time 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 a new platform 1.5 bug fix release is available.
See below in the section on <<howto-link-boot-version,linking versions>> for more examples. See below in the section on <<howto-link-platform-version,linking versions>> for more examples.
@ -795,7 +797,8 @@ URL parameter is specified with curly braces, something like
The following attributes are currently supported: The following attributes are currently supported:
* `bootVersion`: the Spring Boot version that is currently active * `bootVersion`: the platform version that is currently active (named `bootVersion` for
backward compatibility with the metadata format)
Here is an example that adds two links to the `acme` dependency: Here is an example that adds two links to the `acme` dependency:
@ -856,16 +859,16 @@ First, a table that describes the <<create-instance-types,available project type
Then, a table that describes the <<initializr-generator-project,available parameters>>. Then, a table that describes the <<initializr-generator-project,available parameters>>.
Finally, the list of dependencies are defined. Each entry provides the identifier that 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 you'll have to use if you want to select the dependency, a description and the
version range, if any. compatibility range, if any.
Alongside the capabilities of the service, you'll also find a few examples that help you 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 understand how you can generate a project. These are obviously tailored to the client that
you are using. you are using.
Let's assume that you want to generate a "my-project.zip" project based on Spring Boot Let's assume that you want to generate a "my-project.zip" project based on version
`2.3.5.RELEASE`, using the `web` and `devtools` dependencies (remember, those two ids are `2.3.5.RELEASE` of the platform, using the `web` and `devtools` dependencies (remember,
displayed in the capabilities of the service): those two ids are displayed in the capabilities of the service):
[source] [source]
---- ----
@ -903,18 +906,18 @@ that often arise when configuring Spring Initializr.
[[howto-add-a-new-dependency]] [[howto-add-a-new-dependency]]
=== 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 a new dependency, first identify the Maven coordinates of the dependency you want
to add (`groupId:artifactId:version`) and then check which versions of Spring Boot it works to add (`groupId:artifactId:version`) and then check which versions of the platform it
with. If there are multiple versions that work with different versions of Spring Boot, works with. If there are multiple versions that work with different versions of the
then that's fine too. platform, then that's fine too.
* If there is a published BOM that manages the version of you dependency, then add that * If there is a published BOM that manages the version of you dependency, then add that
first, in the `env` section (see <<create-instance-boms>>). first, in the `env` section (see <<create-instance-boms>>).
* Then configure the dependency, fitting it into an existing group if you can, otherwise * Then configure the dependency, fitting it into an existing group if you can, otherwise
creating a new group. creating a new group.
* If there is a BOM then omit the version. * 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 * If there is a compatibility version range (or min or max) that you need for this
dependency, add that as a <<howto-link-boot-version,linked version>>. dependency, add that as a <<howto-link-platform-version,linked version>>.
@ -925,7 +928,7 @@ conflict with the newest version. Or maybe this is the case for only a range of
Boot versions. Or maybe there just is no BOM, or it's not worth creating one for just one 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 dependency. In these cases you can specify the version manually for a dependency either
at the top level, or in a at the top level, or in a
<<howto-link-boot-version,version mapping>>. At the top level it looks like this (just <<howto-link-platform-version,version mapping>>. At the top level it looks like this (just
a `version` property in a dependency): a `version` property in a dependency):
[source,yaml,indent=0] [source,yaml,indent=0]
@ -944,14 +947,14 @@ a `version` property in a dependency):
[[howto-link-boot-version]] [[howto-link-platform-version]]
=== Link a Boot version to a version of your dependency === Link a version of the platform to a version of your dependency
If your dependency requires a specific version of Spring Boot, ot different versions of If your dependency requires a specific version of the platform, ot different versions of
Spring Boot require different versions of your dependency there are a couple of mechanisms the platform require different versions of your dependency there are a couple of
to configure that. mechanisms to configure that.
The simplest is to put a `compatibilityRange` in the dependency declaration. This is a The simplest is to put a `compatibilityRange` in the dependency declaration. This is a
range of versions of Spring Boot, not of your dependency. For example: range of versions of the platform, not of your dependency. For example:
[source,yaml,indent=0] [source,yaml,indent=0]
---- ----
@ -969,10 +972,11 @@ range of versions of Spring Boot, not of your dependency. For example:
compatibilityRange: "[1.5.0.RC1,2.0.0.M1)" compatibilityRange: "[1.5.0.RC1,2.0.0.M1)"
---- ----
In this example `Foo` is available for Spring Boot 1.2.0 (or any milestone of 1.2.0) or In this example `Foo` is available for as of `1.2.0` of the platform, and `Bar` is
greater, and `Bar` is available for Spring Boot 1.5.0 up to, but not including 2.0.0. available for versions of the platform starting at `1.5.0.RC1` and up to, but not
including, `2.0.0.M1`.
If different versions of your dependency work with different versions of Spring Boot, If different versions of your dependency work with different versions of the platform,
that's when you need the `mappings` property. A mapping is a combination of a that's when you need the `mappings` property. A mapping is a combination of a
`compatibilityRange` and some or all of the other properties of the dependency, overriding `compatibilityRange` and some or all of the other properties of the dependency, overriding
the values defined at the top level. For example: the values defined at the top level. For example:
@ -996,8 +1000,8 @@ the values defined at the top level. For example:
---- ----
In this example, The artifact of `foo` was changed to `foo-spring-boot-starter` as of the 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 version that is compatible as of `1.4.0` of the platform. This mapping instructs that if
1.3.x is selected, the artifact Id should be set to `foo-starter`. `1.3.x` of the platform is selected, the artifactId should be set to `foo-starter`.
A mapping can also be applied to a BOM declaration. For example: A mapping can also be applied to a BOM declaration. For example:
@ -1019,9 +1023,9 @@ A mapping can also be applied to a BOM declaration. For example:
repositories: my-api-repo-2 repositories: my-api-repo-2
---- ----
In this example Spring Boot versions up to 1.1.6 select version 1.0.0 of the BOM, and set In this example, versions of the platform 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 and set a different repository. Versions of the platform as of `1.2.1` select `2.0.0` of
yet another repository. the BOM and yet another repository.
@ -1030,8 +1034,8 @@ yet another repository.
A dependency, or a BOM, might require the use of a specific repository, if the default one 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 (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 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 the dependency itself. You can also use a platform <<dependencies-mappings,version
repository,version mapping>> to override the default repository for a dependency or BOM. mapping>> to override the default repository for a dependency or BOM.
@ -1071,7 +1075,7 @@ existing Spring Boot starter) you can flag it as a "non starter":
id: lib id: lib
groupId: com.acme groupId: com.acme
artifactId: lib artifactId: lib
starter:false starter: false
---- ----
When a project is generated that only has dependencies with this flag set, then the base When a project is generated that only has dependencies with this flag set, then the base
@ -1097,8 +1101,8 @@ common settings in a group are the `groupId`, `compatibilityRange` and `bom`:
... ...
---- ----
These dependencies, by default, will be available only for Spring Boot versions 1.3 up to These dependencies, by default, will be available only for versions of the platform as of
2.0 (excluded) and will bring in the `stuff-bom` BOM. `1.3.0.RELEASE` up to `2.0.0.M1` (excluded) and will bring in the `stuff-bom` BOM.
@ -1173,8 +1177,8 @@ one will require some configuration to get it working):
|`initializr.metadata` |`initializr.metadata`
|Cache the full metadata of the service. When the metadata expires, it is fully resolved |Cache the full metadata of the service. When the metadata expires, it is fully resolved
again (including a check on spring.io for the latest Spring Boot versions). Adapt the again (which may include a network call to determine the latest platform versions). Adapt
expiration settings accordingly. the expiration settings accordingly.
|`initializr.dependency-metadata` |`initializr.dependency-metadata`
|Cache dependency-specific metadata. |Cache dependency-specific metadata.

8
initializr-docs/src/main/asciidoc/metadata-format.adoc
View File

@ -45,7 +45,7 @@ component responsible to generate the project (for instance, generate an executa
_jar_ project). _jar_ project).
* Java version: the supported java versions * Java version: the supported java versions
* Language: the language to use (e.g. Java) * Language: the language to use (e.g. Java)
* Boot version: the Spring Boot version to use * Boot version: the platform version to use
* Additional basic information such as: `groupId`, `artifactId`, `version`, `name`, * Additional basic information such as: `groupId`, `artifactId`, `version`, `name`,
`description` and `packageName`. `description` and `packageName`.
@ -168,10 +168,10 @@ include::{snippets}/metadataWithCurrentAcceptHeader/response-fields/language.val
=== Boot version === Platform versions
The `bootVersion` element provides the list of available boot versions The `bootVersion` element provides the list of available platform versions
.Spring Boot version example .Platform versions example
include::{snippets}/metadataWithCurrentAcceptHeader/response-fields/bootVersion.values.0.adoc[] include::{snippets}/metadataWithCurrentAcceptHeader/response-fields/bootVersion.values.0.adoc[]