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-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
on project generation
* `initializr-docs`: documentation
on project generation.
* `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
The `initializr-generator` module contains the low-level infrastructure necessary to
generate JVM-based projects.
[[initializr-generator-project]]
==== Project Generator
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
generate uses the "Gradle" `BuildSystem` and "war" `Packaging`. Check the
`io.spring.initializr.generator.condition` package for more conditions. Also, custom
conditions can easily be created by inheriting from `ProjectGenerationCondition`. Finally,
any use of those conditions should be done on beans registered in the
`ProjectGenerationContext` (i.e. via a `@ProjectGenerationConfiguration` class).
`io.spring.initializr.generator.condition` package for more conditions. You can create
custom conditions easily by inheriting from `ProjectGenerationCondition`.
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 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
``ProjectDescriptionCustomizer``s, the generator uses a `ProjectAssetGenerator` to
generate the project assets. The `initializr-generator` provides a default implementation
of this interface (``DefaultProjectAssetGenerator`) that generates a directory structure
using available `ProjectContributor` beans.
generate the project assets. The `initializr-generator` module provides a default
implementation of this interface (``DefaultProjectAssetGenerator`) that generates a
directory structure using available `ProjectContributor` beans.
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
@@ -148,11 +160,11 @@ Adding new implementations for these involves creating a `BuildSystemFactory`,
`io.spring.initializr.generator.language.LanguageFactory` and
`io.spring.initializr.generator.packaging.PackagingFactory` respectively.
A JVM project typically contains a build file which contains the build configuration for
the project. The `initializr-generator` module provides a model for `Build` with
implementations for `Maven` and `Gradle`. This model can be manipulated depending on the
conventions. The library also provides a `MavenBuildWriter` and `GradleBuildWriter` that
can convert a `Build` model to build file(s).
A JVM project typically contains a build configuration for the project. The
`initializr-generator` module provides a model for `Build` with implementations for
`Maven` and `Gradle`. This model can be manipulated depending on the conventions. The
library also provides a `MavenBuildWriter` and `GradleBuildWriter` that can convert a
`Build` model to build file(s).
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
@@ -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
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
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>
<groupId>io.spring.initializr</groupId>
<artifactId>initializr-bom</artifactId>
<version>{spring-initializr-version}</version>
<type>pom</type>
<scope>import</scope>
<version>{spring-initializr-version}</version>
</dependency>
</dependencies>
</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
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
@@ -328,15 +337,14 @@ The available packagings are also configurable that way:
default: false
----
NOTE: `Jar` and `War` packaging is available out-of-the-box. For additional packaging
formats, you need to implement the `Packaging` abstraction and provide a
NOTE: `Jar` and `War` packaging types are available out-of-the-box. For additional
packaging formats, you need to implement the `Packaging` abstraction and provide a
`PackagingFactory` that corresponds to it.
[[create-instance-text-only-settings]]
=== Configuring text-only settings
Text-only capabilities include `groupId`, `artifactId`, `name`, `description`, `version`
and `packageName`. Each capability has a default value if nothing is configured. The
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.
--
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
dependencies and versions.
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
which is available at https://start.spring.io
* <<user-guide.adoc#user-guide>>: This section is about how to use our default instance of
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
using the jars as libraries in your own app.
* <<configuration-guide.adoc#configuration-guide>>: This section covers creating your own
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.
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).
You can easily create your own instance of the Spring Initializr, by using the jars as libraries
in your own app. There is minimal code involved and the service has a very rich
You can easily create your own instance using Spring Initializr, by using the jars as
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
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
@@ -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
<<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
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

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]
--
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
get a better insight at what you can do with it.
this section is for you! You'll find the various ways you can interact with the service
and get a better insight at what you can do with it.
The service allows you to generate Spring Boot projects quickly.
You can customize the project to generate: the build system and packaging, the language,
the packaging, the coordinates, the platform version and, finally, the dependencies to add
to the project. Most dependencies available on https://start.spring.io are Spring Boot starters
The service allows you to generate Spring Boot projects quickly. You can customize the
project to generate: the build system and packaging, the language, the packaging,
the coordinates, the platform version and, finally, the dependencies to add to the
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.
--
@@ -36,6 +36,7 @@ Click on `Generate Project`, this downloads a zip file containing a Maven projec
the following structure:
```
.gitignore
mvnw
mvnw.cmd
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
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`
directories have been created to hold your static resources and UI templates.
Because Spring Initializr has detected it is a web application, the `static` and
`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
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-based project that also contains a wrapper which can be used if you don't have Gradle
installed (build it with `./gradlew build`).
Gradle-based project that also contains a wrapper which can be used if you don't have
Gradle installed (build it with `./gradlew build`).
[[getting-started-advanced-options]]
=== Advanced options
Below the `Artifact` form field, you'll find an "Options" link. If you click on that, you'll see
all the available options. Let's browse through them quickly:
Below the `Artifact` form field, you'll find an "Options" link. If you click on that,
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`
attribute in Apache Maven). Also infers the root package name to use.
@@ -88,7 +89,7 @@ will have a `MyAppApplication` class
attribute is used
* *Packaging*: project packaging (as referred by the concept of the same name in Apache
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;
```
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
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
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
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.
[[getting-started-tuning-defaults]]
=== Tuning default values
A Spring Initializr service is configured to offer default values so that you can generate a
new project with minimum fuss. Maybe you are a Kotlin fan? Or a Gradle fan? Currently
A Spring Initializr service is configured to offer default values so that you can generate
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
easily.
You can share or bookmark URLs that will automatically customize form inputs. For
instance, the following URL changes the default to use Kotlin and Gradle:
You can share or bookmark URLs that will automatically customize form inputs. You can use
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
@@ -139,6 +142,8 @@ https://start.spring.io/#!language=kotlin&type=gradle-project
The following attributes are supported:
* Spring Boot version: `platformVersion`
* Dependencies: `dependencies`
* Programming language: `language` (`java`, `groovy` or `kotlin`)
* Java version: `javaVersion` (`1.8`, `11`, `12`)
* 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
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.
NOTE: If the Spring Boot version is outdated, the UI will request you to make a choice
and select a supported version.
[[command-line]]
== Command line support
@@ -187,12 +194,12 @@ understand how you can generate a project. These are obviously tailored to the c
you are using.
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):
```
$ 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
@@ -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 \
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
@@ -224,7 +231,8 @@ The following IDEs have dedicated support:
* Eclipse/STS
* 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
Refer to the documentation of your favorite IDE for more details.