lsm/initializr
1
0
Fork 0
mirror of https://gitee.com/dcren/initializr.git synced 2026-02-25 21:22:58 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Polish doc

Browse Source
This commit is contained in:
Stephane Nicoll
2019-10-03 11:31:08 +02:00
parent e56dc0ce17
commit 42976ca9f7
4 changed files with 80 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -16,23 +16,33 @@ the core concepts of project generation and how the library is structured to sup
Initializr is split across several modules: Initializr is split across several modules:
* `initializr-generator`: core project generation library
* `initializr-generator-spring`: optional module defining the conventions for a Spring
Boot project. Can be replaced by your own conventions if necessary.
* `initializr-metadata`: metadata infrastructure for various aspects of the project
* `initializr-web`: REST endpoints
* `initializr-actuator`: optional module to provide additional information and statistics * `initializr-actuator`: optional module to provide additional information and statistics
on project generation on project generation.
* `initializr-docs`: documentation * `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-generator-test`: test infrastructure for project generation.
* `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 from an
arbitrary POM.
* `initializr-web`: web endpoints for third party clients.
To understand concepts behind project generation, let's take a look at
`initializr-generator` and `initializr-generator-spring` in a little more detail.
To understand concepts behind project generation, let's take a look at the first two in
a little more detail.
[[initializr-generator]] [[initializr-generator]]
=== Initializr Generator === Initializr Generator
The `initializr-generator` module contains the low-level infrastructure necessary to The `initializr-generator` module contains the low-level infrastructure necessary to
generate JVM-based projects. generate JVM-based projects.
[[initializr-generator-project]] [[initializr-generator-project]]
==== Project Generator ==== Project Generator
The `ProjectGenerator` class is the main entry point for project generation. A The `ProjectGenerator` class is the main entry point for project generation. A
@@ -82,10 +92,12 @@ to do something and makes the declaration more idiomatic. Consider the following
This registers a component that can customize a Gradle build only if the project to This registers a component that can customize a Gradle build only if the project to
generate uses the "Gradle" `BuildSystem` and "war" `Packaging`. Check the generate uses the "Gradle" `BuildSystem` and "war" `Packaging`. Check the
`io.spring.initializr.generator.condition` package for more conditions. Also, custom `io.spring.initializr.generator.condition` package for more conditions. You can create
conditions can easily be created by inheriting from `ProjectGenerationCondition`. Finally, custom conditions easily by inheriting from `ProjectGenerationCondition`.
any use of those conditions should be done on beans registered in the
`ProjectGenerationContext` (i.e. via a `@ProjectGenerationConfiguration` class). You can only use such conditions on beans that have been loaded on the
`ProjectGenerationConfiguration` as they require a concrete `ProjectDescription` bean
to operate properly.
Project generation may also rely on infrastructure that is not specific to a particular Project generation may also rely on infrastructure that is not specific to a particular
project configuration and is usually configured in the main `ApplicationContext` to avoid project configuration and is usually configured in the main `ApplicationContext` to avoid
@@ -121,9 +133,9 @@ beans and can be ordered using Spring's `Ordered` interface.
Once the description has been customized based on the available Once the description has been customized based on the available
``ProjectDescriptionCustomizer``s, the generator uses a `ProjectAssetGenerator` to ``ProjectDescriptionCustomizer``s, the generator uses a `ProjectAssetGenerator` to
generate the project assets. The `initializr-generator` provides a default implementation generate the project assets. The `initializr-generator` module provides a default
of this interface (``DefaultProjectAssetGenerator`) that generates a directory structure implementation of this interface (``DefaultProjectAssetGenerator`) that generates a
using available `ProjectContributor` beans. directory structure using available `ProjectContributor` beans.
While the default `ProjectAssetGenerator` use the file system and invoke a particular set While the default `ProjectAssetGenerator` use the file system and invoke a particular set
of components, it is possible to use the same `ProjectGenerator` instance with a custom of components, it is possible to use the same `ProjectGenerator` instance with a custom
@@ -148,11 +160,11 @@ Adding new implementations for these involves creating a `BuildSystemFactory`,
`io.spring.initializr.generator.language.LanguageFactory` and `io.spring.initializr.generator.language.LanguageFactory` and
`io.spring.initializr.generator.packaging.PackagingFactory` respectively. `io.spring.initializr.generator.packaging.PackagingFactory` respectively.
A JVM project typically contains a build file which contains the build configuration for A JVM project typically contains a build configuration for the project. The
the project. The `initializr-generator` module provides a model for `Build` with `initializr-generator` module provides a model for `Build` with implementations for
implementations for `Maven` and `Gradle`. This model can be manipulated depending on the `Maven` and `Gradle`. This model can be manipulated depending on the conventions. The
conventions. The library also provides a `MavenBuildWriter` and `GradleBuildWriter` that library also provides a `MavenBuildWriter` and `GradleBuildWriter` that can convert a
can convert a `Build` model to build file(s). `Build` model to build file(s).
The next section about the <<initializr-generator-spring,`initializr-generator-spring`>> The next section about the <<initializr-generator-spring,`initializr-generator-spring`>>
module showcases how the `Build` can be manipulated before the build file is written module showcases how the `Build` can be manipulated before the build file is written
@@ -194,7 +206,7 @@ dependencies and BOMs based on their id in the metadata
If you are using a parent context, it is advised to configure those there as you should If you are using a parent context, it is advised to configure those there as you should
not register them every time a new project is generated: not register them every time a new project is generated:
* An `IndentingWriterFactory` that represents that indenting strategy to use. * An `IndentingWriterFactory` that represents the indenting strategy to use.
* A `MustacheTemplateRenderer` using `classpath:/templates` as root location. Consider * A `MustacheTemplateRenderer` using `classpath:/templates` as root location. Consider
registering such bean with a cache strategy to avoid resolving templates every time. registering such bean with a cache strategy to avoid resolving templates every time.
@@ -241,9 +253,9 @@ Create a new project with the `web` dependency and add the following dependencie
<dependency> <dependency>
<groupId>io.spring.initializr</groupId> <groupId>io.spring.initializr</groupId>
<artifactId>initializr-bom</artifactId> <artifactId>initializr-bom</artifactId>
<version>{spring-initializr-version}</version>
<type>pom</type> <type>pom</type>
<scope>import</scope> <scope>import</scope>
<version>{spring-initializr-version}</version>
</dependency> </dependency>
</dependencies> </dependencies>
</dependencyManagement> </dependencyManagement>
@@ -263,9 +275,6 @@ dependencyManagement {
} }
---- ----
NOTE: Spring Initializr releases are not available on Maven Central so you will need to
configure the build to add an extra repository at `https://repo.spring.io/release`.
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 (except the one for the Spring Boot version, we will
@@ -328,15 +337,14 @@ The available packagings are also configurable that way:
default: false default: false
---- ----
NOTE: `Jar` and `War` packaging is available out-of-the-box. For additional packaging NOTE: `Jar` and `War` packaging types are available out-of-the-box. For additional
formats, you need to implement the `Packaging` abstraction and provide a packaging formats, you need to implement the `Packaging` abstraction and provide a
`PackagingFactory` that corresponds to it. `PackagingFactory` that corresponds to it.
[[create-instance-text-only-settings]] [[create-instance-text-only-settings]]
=== Configuring text-only settings === Configuring text-only settings
Text-only capabilities include `groupId`, `artifactId`, `name`, `description`, `version` Text-only capabilities include `groupId`, `artifactId`, `name`, `description`, `version`
and `packageName`. Each capability has a default value if nothing is configured. The and `packageName`. Each capability has a default value if nothing is configured. The
defaults can be overridden as shown below: defaults can be overridden as shown below:

16
initializr-docs/src/main/asciidoc/documentation-overview.adoc
View File

@@ -8,24 +8,24 @@ think of it as map for the rest of the document. Some sections are targeted to a
audience so this reference guide is not meant to be read in a linear fashion. audience so this reference guide is not meant to be read in a linear fashion.
-- --
Spring Initializr provides an extensible API to generate quickstart projects, and to Spring Initializr provides an extensible API to generate JVM-based projects, and to
inspect the metadata used to generate projects, for instance to list the available inspect the metadata used to generate projects, for instance to list the available
dependencies and versions. dependencies and versions.
The documentation is roughly divided into three parts: The documentation is roughly divided into three parts:
* <<user-guide.adoc#user-guide>>: This section is about how to use our default instance of Spring Initializr * <<user-guide.adoc#user-guide>>: This section is about how to use our default instance of
which is available at https://start.spring.io Spring Initializr which is available at https://start.spring.io
* <<configuration-guide.adoc#configuration-guide>>: This section covers creating your own instance of Spring Initializr * <<configuration-guide.adoc#configuration-guide>>: This section covers creating your own
using the jars as libraries in your own app. instance of Spring Initializr using the jars as libraries in your own app.
* <<api-guide.adoc#api-guide>>: This section covers the API used for project generation. * <<api-guide.adoc#api-guide>>: This section covers the API used for project generation.
The API can be used standalone or embedded in other tools (e.g. it is used in major IDEs The API can be used standalone or embedded in other tools (e.g. it is used in major IDEs
such as Spring Tool Suite, IntelliJ IDEA Ultimate, Netbeans and VSCode). such as Spring Tool Suite, IntelliJ IDEA Ultimate, Netbeans and VSCode).
You can easily create your own instance of the Spring Initializr, by using the jars as libraries You can easily create your own instance using Spring Initializr, by using the jars as
in your own app. There is minimal code involved and the service has a very rich libraries 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 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 attributes but also the list of dependencies and the constraints to apply to them. If that
sounds interesting, then <<configuration-guide.adoc#configuration-guide>> has all the sounds interesting, then <<configuration-guide.adoc#configuration-guide>> has all the
@@ -34,7 +34,7 @@ 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 one. For those and other simple and common use cases check out
<<configuration-guide.adoc#configuration-howto>>. <<configuration-guide.adoc#configuration-howto>>.
Spring Initializr also provides an extensible API to generate quickstart projects, and to Spring Initializr also provides an extensible API to generate JVM-based projects, and to
inspect the metadata used to generate projects, for instance to list the available 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 dependencies and versions. The API can be used standalone or embedded in other tools
(e.g. it is used in major IDEs such as Spring Tool Suite, IntelliJ IDEA Ultimate, Netbeans (e.g. it is used in major IDEs such as Spring Tool Suite, IntelliJ IDEA Ultimate, Netbeans

BIN
initializr-docs/src/main/asciidoc/images/web-selected.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 745 KiB

After

Width:  |  Height:  |  Size: 777 KiB

62
initializr-docs/src/main/asciidoc/user-guide.adoc
View File

@@ -4,13 +4,13 @@
[partintro] [partintro]
-- --
If you're wondering how to use https://start.spring.io or what features are available, If you're wondering how to use https://start.spring.io or what features are available,
this section is for you! You'll find the various ways you can interact with the service and this section is for you! You'll find the various ways you can interact with the service
get a better insight at what you can do with it. and get a better insight at what you can do with it.
The service allows you to generate Spring Boot projects quickly. The service allows you to generate Spring Boot projects quickly. You can customize the
You can customize the project to generate: the build system and packaging, the language, project to generate: the build system and packaging, the language, the packaging,
the packaging, the coordinates, the platform version and, finally, the dependencies to add the coordinates, the platform version and, finally, the dependencies to add to the
to the project. Most dependencies available on https://start.spring.io are Spring Boot starters project. Most dependencies available on https://start.spring.io are Spring Boot starters
which is the recommended way to add dependencies to a Spring Boot application. which is the recommended way to add dependencies to a Spring Boot application.
-- --
@@ -36,6 +36,7 @@ Click on `Generate Project`, this downloads a zip file containing a Maven projec
the following structure: the following structure:
``` ```
.gitignore
mvnw mvnw
mvnw.cmd mvnw.cmd
pom.xml pom.xml
@@ -60,21 +61,21 @@ A typical project generated by Spring Initializr contains a Spring Boot applicat
(`DemoApplication`), a test and an empty configuration. If you run the `main` method (`DemoApplication`), a test and an empty configuration. If you run the `main` method
of `DemoApplication`, you'll see an "empty" spring boot app starting on localhost:8080. of `DemoApplication`, you'll see an "empty" spring boot app starting on localhost:8080.
Because Spring Initializr has detected it is a web application, the `static` and `templates` Because Spring Initializr has detected it is a web application, the `static` and
directories have been created to hold your static resources and UI templates. `templates` directories have been created to hold your static resources and UI templates.
Also, a Maven wrapper is automatically included so that you don't have to install Maven to Also, a Maven wrapper is automatically included so that you don't have to install Maven to
run this project (you can build it with `./mvnw install`). If you prefer, you can select run this project (you can build it with `./mvnw install`). If you prefer, you can select
Gradle instead in the first option at the top of the screen. This will generate a Gradle instead in the first option at the top of the screen. This will generate a
Gradle-based project that also contains a wrapper which can be used if you don't have Gradle Gradle-based project that also contains a wrapper which can be used if you don't have
installed (build it with `./gradlew build`). Gradle installed (build it with `./gradlew build`).
[[getting-started-advanced-options]] [[getting-started-advanced-options]]
=== Advanced options === Advanced options
Below the `Artifact` form field, you'll find an "Options" link. If you click on that, you'll see Below the `Artifact` form field, you'll find an "Options" link. If you click on that,
all the available options. Let's browse through them quickly: you'll see all the available options. Let's browse through them quickly:
* *Group*: project coordinates (id of the project's group, as referred by the `groupId` * *Group*: project coordinates (id of the project's group, as referred by the `groupId`
attribute in Apache Maven). Also infers the root package name to use. attribute in Apache Maven). Also infers the root package name to use.
@@ -88,7 +89,7 @@ will have a `MyAppApplication` class
attribute is used attribute is used
* *Packaging*: project packaging (as referred by the concept of the same name in Apache * *Packaging*: project packaging (as referred by the concept of the same name in Apache
Maven). start.spring.io can generate jar or war projects Maven). start.spring.io can generate jar or war projects
* *Java Version*: the Java version to use * *Java*: the Java version to use
@@ -105,33 +106,35 @@ panel, it indicates that you cannot use it with the currently selected Spring Bo
version; version;
``` ```
Requires Spring Boot >=1.5.0.RELEASE and <2.0.0.RELEASE Requires Spring Boot >=2.0.0.RELEASE and <2.1.0.RELEASE
``` ```
Concretely, this defines a "version range" that states the dependency is deprecated and is Concretely, this defines a "version range" that states the dependency is deprecated and is
no longer available as of Spring Boot 2.0. You may want to check the release notes of the no longer available as of Spring Boot 2.1. You may want to check the release notes of the
related project to understand what your migration path can be. Alternatively, the message related project to understand what your migration path can be. Alternatively, the message
could be: could be:
``` ```
Requires Spring Boot >=2.1.0.RELEASE Requires Spring Boot >=2.2.0.RELEASE
``` ```
That version range means the dependency is not available with the selected Spring Boot That version range means the dependency is not available with the selected Spring Boot
generation. If you select Spring Boot 2.1 (or later if available), you'll be generation. If you select Spring Boot 2.2 (or later if available), you'll be
able to select that dependency. able to select that dependency.
[[getting-started-tuning-defaults]] [[getting-started-tuning-defaults]]
=== Tuning default values === Tuning default values
A Spring Initializr service is configured to offer default values so that you can generate a A Spring Initializr service is configured to offer default values so that you can generate
new project with minimum fuss. Maybe you are a Kotlin fan? Or a Gradle fan? Currently a new project with minimum fuss. Maybe you are a Kotlin fan? Or a Gradle fan? Currently
start.spring.io defaults to Java and Maven but it also allows you to tune these defaults start.spring.io defaults to Java and Maven but it also allows you to tune these defaults
easily. easily.
You can share or bookmark URLs that will automatically customize form inputs. For You can share or bookmark URLs that will automatically customize form inputs. You can use
instance, the following URL changes the default to use Kotlin and Gradle: the `share` action to generate the URL based on your current selection. The URL contains
all attributes but you can remove the ones you're not interested. For instance, the
following URL changes the default to use Kotlin and Gradle:
``` ```
https://start.spring.io/#!language=kotlin&type=gradle-project https://start.spring.io/#!language=kotlin&type=gradle-project
@@ -139,6 +142,8 @@ https://start.spring.io/#!language=kotlin&type=gradle-project
The following attributes are supported: The following attributes are supported:
* Spring Boot version: `platformVersion`
* Dependencies: `dependencies`
* Programming language: `language` (`java`, `groovy` or `kotlin`) * Programming language: `language` (`java`, `groovy` or `kotlin`)
* Java version: `javaVersion` (`1.8`, `11`, `12`) * Java version: `javaVersion` (`1.8`, `11`, `12`)
* Project type: `type` (`maven-project`, `gradle-project`) * Project type: `type` (`maven-project`, `gradle-project`)
@@ -152,8 +157,10 @@ The following attributes are supported:
TIP: The same default rules will apply if a property is overridden. For instance, if the 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. 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 NOTE: If the Spring Boot version is outdated, the UI will request you to make a choice
as they evolve quite frequently. and select a supported version.
[[command-line]] [[command-line]]
== Command line support == Command line support
@@ -187,12 +194,12 @@ understand how you can generate a project. These are obviously tailored to the c
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 Spring Boot
`2.1.2.RELEASE`, using the `web` and `devtools` dependencies (remember, those two ids are `2.1.9.RELEASE`, using the `web` and `devtools` dependencies (remember, those two ids are
displayed in the capabilities of the service): displayed in the capabilities of the service):
``` ```
$ curl https://start.spring.io/starter.zip -d dependencies=web,devtools \ $ curl https://start.spring.io/starter.zip -d dependencies=web,devtools \
-d bootVersion=2.1.2.RELEASE -o my-project.zip -d bootVersion=2.1.9.RELEASE -o my-project.zip
``` ```
If you extract `my-project.zip`, you'll notice a few differences compared to what happens If you extract `my-project.zip`, you'll notice a few differences compared to what happens
@@ -207,7 +214,7 @@ The exact same project can be generated using the `http` command as well:
``` ```
$ http https://start.spring.io/starter.zip dependencies==web,devtools \ $ http https://start.spring.io/starter.zip dependencies==web,devtools \
bootVersion==1.5.1.RELEASE -d bootVersion==2.1.9.RELEASE -d
``` ```
NOTE: `HTTPie` reads the same hint as the browser so it will store a `demo.zip` file in NOTE: `HTTPie` reads the same hint as the browser so it will store a `demo.zip` file in
@@ -224,7 +231,8 @@ The following IDEs have dedicated support:
* Eclipse/STS * Eclipse/STS
* IntelliJ IDEA (Ultimate Edition) * IntelliJ IDEA (Ultimate Edition)
* NetBeans (using the https://plugins.netbeans.org/plugin/67888/nb-springboot[NB SpringBoot plugin]) * NetBeans (using the https://plugins.netbeans.org/plugin/67888/nb-springboot[NB
SpringBoot plugin])
* Microsoft VSCode * Microsoft VSCode
Refer to the documentation of your favorite IDE for more details. Refer to the documentation of your favorite IDE for more details.