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

Initiate ref guide overhaul

Browse Source 
See gh-392
This commit is contained in:
Stephane Nicoll 2017-03-30 14:36:16 +02:00
parent 0e3216e3ac
commit bbaf3d3b2f
5 changed files with 643 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
initializr-docs/pom.xml
View File

@ -103,6 +103,7 @@
<docinfo>true</docinfo>
<spring-initializr-version>${project.version}</spring-initializr-version>
<spring-initializr-docs-version>${project.version}</spring-initializr-docs-version>
<spring-boot-docs-version>${spring.boot.version}</spring-boot-docs-version>
<snippets>${snippets.location}</snippets>
<github-tag>${github-tag}</github-tag>
</attributes>
@ -192,25 +193,7 @@
</postProcess>
</configuration>
</execution>
<execution>
<id>pdf</id>
<goals>
<goal>generate-pdf</goal>
</goals>
<phase>prepare-package</phase>
<configuration>
<foCustomization>${basedir}/src/main/docbook/xsl/pdf.xsl</foCustomization>
<targetDirectory>${basedir}/target/docbook/pdf</targetDirectory>
<postProcess>
<copy todir="${basedir}/target/contents/reference">
<fileset dir="${basedir}/target/docbook">
<include name="**/*.pdf" />
</fileset>
</copy>
<move file="${basedir}/target/contents/reference/pdf/index.pdf" tofile="${basedir}/target/contents/reference/pdf/initializr-reference.pdf" />
</postProcess>
</configuration>
</execution>
<execution>
<id>epub</id>
<goals>

387
initializr-docs/src/main/asciidoc/configuration-guide.adoc Normal file
View File

@ -0,0 +1,387 @@
[[configuration-guide]]
= Configuration Guide
[partintro]
--
This section describes how you can create your own instance of the service and tune it for
your needs. You'll also find some advanced tips to make sure the available options are
consistent with the chosen Spring Boot generation.
--
[[create-instance]]
== Creating your own instance
Spring Initializr is split in three main modules:
* `initializr-generator`: standalone project generation library that can be reused in
many environments (including embedded in your own project)
* `initializr-web`: REST endpoints and web interface
* `initializr-actuator`: optional module to provide statistics and metrics on project
generation
Because it contains several auto-configurations, creating your own instance is quite easy,
actually you could get started using Spring Initializr itself!
Create a new project with the `web` dependency and add the following dependency:
[source,xml,indent=0,subs="verbatim,attributes"]
----
<dependency>
<groupId>io.spring.initializr</groupId>
<artifactId>initializr-web</artifactId>
<version>{spring-initializr-version}</version>
</dependency>
----
Or if you are using Gradle:
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
----
compile("io.spring.initializr:initializr-web:{spring-initializr-version}")
----
If you start the application, you'll see the familiar interface but none of the drop down
lists have values (except the one for the Spring Boot version, we will
<<create-instance-boot-versions,come back to that later>>). In the rest of this section,
we will configure those basic settings.
[TIP]
====
Most of the settings are configured via `application.properties` using the `initializr`
namespace. Because the configuration is highly hierarchical, we recommend using the yaml
format that is more readable for such structure. If you agree, go ahead and rename
`application.properties` to `application.yml`.
====
[[create-instance-basic-settings]]
=== Configuring basic settings
Most of the drop-down lists are configured via a simple list-based structure where each
entry has an `id`, a `name` and whether that entry is the default or not. If no `name` is
provided, the `id` is used instead.
Let's configure the languages and the Java versions we want to support:
[source,yaml,indent=0]
----
initializr:
javaVersions:
- id: 9
default: false
- id: 1.8
default: true
languages:
- name: Java
id: java
default: true
- name: Kotlin
id: kotlin
default: false
----
If you click on the "Switch to the full version" link, the two drop down lists now offer
the options and default values defined above.
Spring Initializr supports `java`, `groovy` and `kotlin` and additional languages can be
added in your own customization.
The available packagings are also configurable that way:
[source,yaml,indent=0]
----
initializr:
packagings:
- name: Jar
id: jar
default: true
- name: War
id: war
default: false
----
These two packaging types are the only one explicitly supported at the moment.
[[create-instance-boot-versions]]
=== Configuring available Spring Boot versions
If you look at http://projects.spring.io/spring-boot[the project home page for Spring
Boot], the latest versions are displayed. And you've probably noticed that they match
the drop down list that you automatically get with a default instance. The reason for that
is that Spring Initializr requests an API on spring.io to retrieve the latest versions
automatically. This makes sure that you always get the latest available versions.
If that's not what you want, you need to override the `InitializrMetadataProvider` bean
that is responsible to provide the metadata of the service. For instance, you could swap
to an implementation that always returns the content of your configuration file:
[source,java,indent=0]
----
@Bean
public InitializrMetadataProvider initializrMetadataProvider(
InitializrProperties properties) {
InitializrMetadata metadata = InitializrMetadataBuilder
.fromInitializrProperties(properties).build();
return new SimpleInitializrMetadataProvider(metadata);
}
----
The thing to remember is that, by default, you don't have to worry about upgrading your
instance when a new Spring Boot version is released. However, you may need to
<<create-instance-advanced-config-caching,configure caching>> to avoid requesting that
service too often.
[[create-instance-types]]
=== Configuring available project types
The available project types mostly define the structure of the generated project and its
build system. Once a project type is selected, the related action is invoked to generate
the project.
By default, Spring Initializr exposes the following actions:
* `/pom.xml` generate a Maven `pom.xml`
* `/build.gradle` generate a Gradle build
* `/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:
* `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
a build file).
By default, the HTML UI filters all the available types to only display the ones that have
a `format` tag with value `project`.
You can of course implement additional endpoints that generate whatever project structure
you need but, for now, we'll simply configure our instance to generate a Gradle or a Maven
project:
[source,yaml,indent=0]
----
initializr:
types:
- name: Maven Project
id: maven-project
description: Generate a Maven based project archive
tags:
build: maven
format: project
default: true
action: /starter.zip
- name: Gradle Project
id: gradle-project
description: Generate a Gradle based project archive
tags:
build: gradle
format: project
default: false
action: /starter.zip
----
NOTE: If you intend to build a custom client against your service, you can add as
many tags as you want.
The spring boot CLI uses them as a shortcut to the full id. So rather than having to
create a Gradle project as follows:
[indent=0,subs="verbatim,quotes,attributes"]
----
$ spring init --type=gradle-project my-project.zip
----
You can simply define a more convenient build parameter:
[indent=0,subs="verbatim,quotes,attributes"]
----
$ spring init --build=gradle my-project.zip
----
With that configuration, you should be able to generate your first project,
congratulations! Let's now add dependencies so that you can start searching for them.
[[create-instance-dependencies]]
=== Configuring dependencies
The most basic `dependency` is composed of:
* An `id` used in clients to refer to it
* The full maven coordinates of the dependency (`groupId` and `artifactId`)
* A display `name` (used in the UI and the search results)
* A `description` can (and should) be added to provide more information about the
dependency
Spring Initializr automatically considers that a dependency without maven coordinates
defines an official Spring Boot starter. In such a case, the `id` is used to infer the
`artifactId`.
For instance, the following configures the `spring-boot-starter-web` Starter:
[source,yaml,indent=0]
----
initializr:
dependencies:
- name: Web
content:
- name: Web
id: web
description: Full-stack web development with Tomcat and Spring MVC
----
Each dependency is contained in a _group_ that gathers dependencies sharing a common
surface area or any other form of grouping. In the example above, a `Web` group holds our
unique dependency. A group can also provide default values for various settings, see the
<<howto-group-share-settings,dedicated how-to>> for more details.
In our `spring-boot-starter-web` example above, the dependency is _managed_ by Spring
Boot so there is no need to provide a `version` attribute for it. You'll surely need to
define additional dependencies that are not provided by Spring Boot and we 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:
[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
----
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
[source,xml,indent=0,subs="verbatim"]
----
<dependency>
<groupId>com.example.acme</groupId>
<artifactId>acme</artifactId>
<version>1.2.0.RELEASE</version>
</dependency>
----
The rest of this section will detail the other configuration options.
[[dependencies-version-range]]
==== Availability (version range)
[[dependencies-mappings]]
==== Map coordinates according to the Spring Boot version
[[dependencies-alias]]
==== Aliases
[[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>>.
[[dependencies-facet]]
==== Facets
[[create-instance-dependencies-link]]
==== Links
[[create-instance-dependencies-search]]
==== Improve search results
Weight + keywords
[[create-instance-repositories]]
=== Configuring Repositories
[[create-instance-boms]]
=== Configuring Bill of Materials
[[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-dependency-starter-flag]]
=== Make sure a regular dependency brings the base starter
[[howto-group-share-settings]]
=== Share common dependency settings in a group
[[create-instance-advanced-config]]
== Advanced configuration
[[create-instance-advanced-config-caching]]
=== Caching configuration
If you use the service, you'll notice that the logs have lots of entries with the message
`Fetching boot metadata from https://spring.io/project_metadata/spring-boot`. To avoid
checking for the latest Spring Boot versions too often, you should enable caching on your
service. Spring Initializr has some auto-configuration to apply the proper caches if you
are willing to use a JCache (JSR-107) implementation.
Add the `javax.cache:cache-api` and your favorite JCache implementation and simply enable
caching by adding `@EnableCaching` to your `@SpringBootApplication`. For instance, you
could use `ehcache` by adding the following:
[source,xml,indent=0,subs="verbatim,attributes"]
----
<dependency>
<groupId>javax.cache</groupId>
<artifactId>cache-api</artifactId>
</dependency>
<dependency>
<groupId>org.ehcache</groupId>
<artifactId>ehcache</artifactId>
</dependency>
----
Or if you are using Gradle:
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
----
compile("javax.cache:cache-api")
compile("org.ehcache:ehcache")
----
You'll notice that the log entry is much more rare. If you do not want to use JSR-107, you
should configure the cache yourselves:
.Cache configuration
|===
| cache name | Description
|`initializr`
|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
expiration settings accordingly.
|`project-resources`
|Cache resources that are used to generate projects.
|`dependency-metadata`
|Cache dependency-specific metadata.
|===

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

@ -1,19 +1,32 @@
[[boot-documentation]]
[[initializr-documentation]]
= Spring Initializr Documentation
Spring Initializr provides an extensible API to generate quickstart projects. It also
provides a configurable service: you can see our default instance at
https://start.spring.io. It provides a simple web UI to configure the project to
generate and endpoints that you can use via plain HTTP.
[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
audience so this reference guide is not meant to be read in a linear fashion.
--
Spring Initializr also exposes an endpoint that serves its metadata in a
<<metadata-format.adoc#metadata-format,well-known format>> to allow third-party
clients to provide the necessary assistance.
Spring Initializr provides an extensible API to generate quickstart projects. Such an API
can be used standalone or embedded in other tools. We also provide a configurable service:
you can see our default instance at https://start.spring.io. It provides a simple web UI
to configure the project to generate and endpoints that you can use via plain HTTP.
Finally, Initializr offers a <<configuration-format.adoc#configuration-format,
configuration structure>> to define all the aspects related to the project to
generate: list of dependencies, supported java and boot versions, etc.
The service allows you to customize the project to generate: the build system and its
coordinates, the language and version, the packaging and finally the dependencies to add
the project. The latter is a core concept: based on the chosen Spring Boot version, a set
of dependencies can be chosen, usually Spring Boot starters, that will have a concrete
impact on your application. More details in the <<user-guide.adoc#user-guide>>.
You can easily create your own instance: 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.
Spring Initializr also exposes an endpoint that serves its metadata in a well-known format
to allow third-party clients to provide the necessary assistance. Currently, all the major
Java IDEs are covered and you can generate a project right from your favourite IDE.
[[initializr-documentation-about]]

10
initializr-docs/src/main/asciidoc/index.adoc
View File

@ -19,13 +19,11 @@ Stéphane Nicoll; Dave Syer
:spring-initializr-docs-version: current
:spring-initializr-docs: http://docs.spring.io/initializr/docs/{spring-initializr-docs-version}/reference
:spring-initializr-docs-current: http://docs.spring.io/initializr/docs/current/reference
:spring-boot-reference: http://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/reference/htmlsingle
// ======================================================================================
include::documentation-overview.adoc[leveloffset=+1]
include::metadata-format.adoc[leveloffset=+1]
include::using-the-stubs.adoc[leveloffset=+1]
include::configuration-format.adoc[leveloffset=+1]
include::documentation-overview.adoc[]
include::user-guide.adoc[]
include::configuration-guide.adoc[]
// ======================================================================================

226
initializr-docs/src/main/asciidoc/user-guide.adoc Normal file
View File

@ -0,0 +1,226 @@
[[user-guide]]
= User Guide
[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 way you can interact with the service and
get a better insight at what you can do with it.
--
[[getting-started]]
== Getting Started
Let's create a first project and discover the various options that you can use to tune it.
Go to https://start.spring.io, change the `Group` field from "com.example" to "org.acme"
and put the focus in the `Dependencies` field on the right hand side. If you type "web",
you will see a list of matching choices with that simple criteria. Use the mouse or the
arrow keys and `Enter` to select the "Web" starter.
Your browser should now be in this state:
TODO: add screenshot
NOTE: The Spring Boot version above probably doesn't match the one you have. As we will
see later, start.spring.io is continuously updated as new Spring Boot versions are
published and the service uses the latest version by default.
Click on `Generate Project`, this downloads a zip file containing a Maven project with
the following structure:
```
mvnw
mvnw.cmd
pom.xml
src
├── main
│   ├── java
│   │   └── org
│   │   └── acme
│   │   └── DemoApplication.java
│   └── resources
│   ├── application.properties
│   ├── static
│   └── templates
└── test
└── java
└── org
└── acme
└── DemoApplicationTests.java
```
A typical project generated by Spring Initializr contains a Spring Boot application
(`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, a `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 select Gradle instead in first drop down list. This will
generate a Gradle-based project instead that also contains a wrapper if you don't have
Gradle installed.
[[getting-started-advanced-options]]
=== Advanced options
Next to the `Generate Project` you'll find a "Switch to the full version" 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.
* *Artifact*: project coordinates (id of the artifact, as referred by the `artifactId`
attribute in Apache Maven). Also infers the name of the project
* *Name*: display name of the project that also determines the name of your Spring Boot
application. For instance, if the name of your project is `my-app`, the generated project
will have a `MyAppApplication` class
* *Description*: description of the project
* *Package Name*: root package of the project. If not specified, the value of the *Group*
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
* *Language*: the programming language to use
If you keep on scrolling, you'll discover all the dependencies that you can find using the
search box on the right. You'll probably notice that some dependencies aren't available
because they require a specific Spring Boot version. We'll tackle that in the next
section.
[[getting-started-dependencies]]
=== Dependencies
The UI allows you to select the Spring Boot version you want to use. You may want to be
conservative and keep the default which corresponds at all times to the latest stable
release. Or you may want to chose a milestone of the next major version. Either way,
you'll notice that certain dependencies become available and others aren't anymore when
you change the version.
If you are searching for a dependency that you know to be available and you get no result,
it's worth looking in the advanced section if that dependency is available in the Spring
Boot version that is currently selected.
You may find it is not the case with a message that looks like the following:
```
requires Spring Boot >=1.0.0.RELEASE and <1.5.0.RC1
```
Concretely, this defines a "version range" that states the dependency is deprecated and is
no longer available as of Spring Boot 1.5. 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.0.0.RELEASE
```
That version range means the dependency is not available with the current Spring Boot
generation. Obviously, if you select Spring Boot 2.0 (or later if available), you'll be
able to select that dependency.
[[getting-started-tuning-defaults]]
=== Tuning default values
The 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:
```
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.
[[command-line]]
== Command line support
You can also generate a project in a shell using `cURL` or `HTTPie`. To discover the
available options of a particular instance, simply "curl it", i.e. if you have `curl`
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
in three sections:
First, a table that describes the available project's types. On the default instance,
you'll find the `maven-project` and `gradle-project` we've discussed above but you'll
also be able to generate only a build script rather than an entire project.
Then, a table that describes the available parameters. For the most part, these are the
same options as the ones available in the web UI. There are, however, a few additional
ones:
* `applicationName` can be used to define the name of the application, disabling the
algorithm that infer it based on the `name` parameter
* `baseDir` can be used to create a base directory in the archive so that you can extract
the generated zip without creating a directory for it first
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
version range, if any.
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
you are using.
Let's assume that you want to generate a "my-project.zip" project based on Spring Boot
`1.5.2.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=1.5.2.RELEASE -o my-project.zip
```
If you extract `my-project.zip`, you'll notice a few differences compared to what happens
with the web UI:
* The project will be extracted in the current directory (the web UI adds a base directory
automatically with the same name as the one of the project)
* The name of the project is not `my-project` (the `-o` parameter has no incidence on the
name of the project)
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
```
NOTE: `HTTPie` reads the same hint as the browser so it will store a `demo.zip` file in
the current directory, with the same differences discussed above.
[[ide]]
== IDEs support
Spring Initializr is also integrated in all major Java IDEs and allows you to create and
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
Refer to the documentation of your favorite IDE for more details.
[[spring-boot-cli]]
== Spring Boot CLI support
The `spring` command line tool defines an `init` command that allows you to create a
project using Spring Initializr.
Check {spring-boot-reference}/#cli-init[the documentation for more details].