mirror of
https://gitee.com/dcren/initializr.git
synced 2026-02-25 21:22:58 +08:00
Polish
This commit is contained in:
Stephane Nicoll
@@ -1,182 +0,0 @@
|
||||
[[configuration-format]]
|
||||
# Configuration Format
|
||||
This section describes the configuration structure that is used by Spring initializr.
|
||||
The metadata provided through configuration are driving the options exposed by a
|
||||
particular instance and <<metadata-format.adoc#metadata-format,the project metadata
|
||||
format>>.
|
||||
|
||||
The configuration is split in several sections:
|
||||
|
||||
* An `env` section used to provide various global settings.
|
||||
* A `dependencies` section lists the available dependencies. This is the most
|
||||
important section of the service as it defines the "libraries" that the user can
|
||||
choose.
|
||||
* The `groupId`, `artifactId`, `version`, `name`, `description` and `packageName`
|
||||
provide default values for these project settings.
|
||||
* The `types`, `packagings`, `javaVersions`, `languages` and `bootVersions` provide
|
||||
the list of available option for each setting and which one is the default.
|
||||
|
||||
|
||||
|
||||
## Env section
|
||||
TIP: Check {sc-initializr-generator}/metadata/InitializrConfiguration.java#L142[the code]
|
||||
for a full list of the available configuration options.
|
||||
|
||||
The `env` element defines environment option that the service uses:
|
||||
|
||||
* `artifactRepository`: the URL of the (maven) repository that should be used to
|
||||
download the Spring Boot CLI distribution bundle. This is only used by the `/spring`
|
||||
endpoint at the moment.
|
||||
* `springBootMetadataUrl` the URL of the resource that provides the list of available
|
||||
Spring Boot versions.
|
||||
* `forceSsl`: a boolean flag that determines if we should redirect browser to `https` when
|
||||
browsing via `http`. Also force the use of `https` in all links. This is not enabled by
|
||||
default to ease local use case but should be enabled in production.
|
||||
* `fallbackApplicationName`: the name of the _default_ application. Application names
|
||||
are generated based on the project's name. However, some user input may result in an
|
||||
invalid identifier for a Java class name for instance.
|
||||
* `invalidApplicationNames`: a fixed list of invalid application names. If a project
|
||||
generation uses one of these names, the fallback is used instead.
|
||||
* `invalidPackageNames`: a fixed list of invalid package names. If a project
|
||||
generation uses one of these names, the default is used instead.
|
||||
* `googleAnalyticsTrackingCode`: the Google Analytics code to use. If this is set,
|
||||
Google analytics is automatically enabled.
|
||||
* `kotlin`: kotlin-specific settings. For now, only the kotlin version to use can be
|
||||
configured and is a mandatory option if Kotlin is enabled.
|
||||
* `maven`: maven-specified settings. A custom maven parent POM can be defined and
|
||||
whether or not the `spring-boot-dependencies` BOM should be automatically added to
|
||||
the project.
|
||||
|
||||
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:
|
||||
|
||||
```yml
|
||||
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.
|
||||
|
||||
## Dependencies section
|
||||
|
||||
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:
|
||||
|
||||
* A mandatory identifier. If no further information is provided, a Spring Boot starer
|
||||
with that id is assumed.
|
||||
* A `name` and `description` used in the generated meta-data and the web ui.
|
||||
* A `groupId` and `artifactId` to define the coordinates of the dependency.
|
||||
* A `version` if Spring Boot does not already provide a dependency management for
|
||||
that dependency.
|
||||
* A `scope` (can be `compile`, `runtime`, `provided` or `test`).
|
||||
* A `classifier` (if the dependency to use is classified, such as `test-jar`).
|
||||
* The reference to a `bom` or a `repository` that must be added to the project once
|
||||
that dependency is added.
|
||||
* A `compatibilityRange` used to determine the platform versions that are compatible
|
||||
with the dependency.
|
||||
* Links to resources such as a guide or a reference doc section.
|
||||
|
||||
TIP: Check {sc-initializr-generator}/metadata/Dependency.java[the code] for a full
|
||||
list of the available configuration options.
|
||||
|
||||
Here is the most basic dependency entry you could have
|
||||
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
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.
|
||||
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
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
|
||||
compatibilityRange: "[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 `compatibilityRange` 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).
|
||||
|
||||
### Dependency group
|
||||
|
||||
A dependency group gather a set of dependencies as well as some common settings:
|
||||
`bom`, `repository` and `compatibilityRange`. If one of them is set, it is applied for all
|
||||
dependencies within that group. It is still possible to override a particular value
|
||||
at the dependency level.
|
||||
|
||||
## Other sections
|
||||
|
||||
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.8` and `11` you would write the following config:
|
||||
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
initializr:
|
||||
groupId:
|
||||
value: org.acme
|
||||
javaVersions:
|
||||
- id: 11
|
||||
default: false
|
||||
- id: 1.8
|
||||
default: true
|
||||
----
|
||||
@@ -1,5 +1,6 @@
|
||||
[[metadata-format]]
|
||||
= Metadata Format
|
||||
|
||||
This section describes the hal/json structure of the metadata exposed by the
|
||||
initializr. Such metadata can be used by third party clients to provide a list of
|
||||
options and default settings that can be used to request the creation of a project.
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
= Using the Stubs
|
||||
|
||||
Spring Initializr project publishes
|
||||
https://github.com/tomakehurst/wiremock[WireMock] stubs for all the JSON responses
|
||||
that are tested in the project. If you are writing a client for Spring Initializr
|
||||
|
||||
Reference in New Issue
Block a user