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

Clarify that this project does not provide a Web UI

Browse Source 
This commit removes any reference to start.spring.io in the reference
guide, moving the user guide there in the process.

Closes gh-1100
This commit is contained in:
Stephane Nicoll
2020-11-16 15:10:17 +01:00
parent d18dcab14f
commit 2cd85513da
10 changed files with 134 additions and 366 deletions
Download Patch File Download Diff File Expand all files Collapse all files

96
README.adoc
View File

@@ -27,7 +27,7 @@ particular, the
{service}/blob/master/start-site/src/main/resources/application.yml[configuration of our
instance]. Such configuration is also described in details in the documentation.
NOTE: While Spring Initializr is now available on Maven Central, it is still in a pre 1.0
NOTE: While Spring Initializr is available on Maven Central, it is still in a pre 1.0
state and major refactoring are still possible. Check the
https://github.com/spring-io/initializr/milestones[milestones page] for an overview of the
changes.
@@ -67,97 +67,6 @@ plugin]).
There are other command-line integrations out there and you can also build your own!
== Generating a project
As Spring Initializr doesn't come with a Web UI, you can use any of the out-of-the-box
integration to generate a project. For instance, the following `curl` command downloads
a project archive with a Maven-based project and the necessary infrastructure to start
a basic Spring Boot app.
[source,bash]
----
$ curl https://start.spring.io/starter.zip -o demo.zip
----
The project to generate can be customized of course with a number of options:
* Basic information for the generated project: `groupId`, `artifactId`, `version`,
`name`, `description` and `packageName`
** The `name` attribute is also used to generate a default application name. The
logic is that the name of the application is equal to the `name` attribute with an
`Application` suffix (unless said suffix is already present). Of course, if the
specified name contains an invalid character for a java identifier, `Application` is
used as fallback.
** The `artifactId` attribute not only defines the identifier of the project in the
build but also the name of the generated archive.
* `dependencies`: the identifiers of the dependencies to add to the
project. Such identifiers are defined through configuration and are exposed in the
<<metadata,metadata>>.
* `type`: the _kind_ of project to generate (e.g. `maven-project`). Again, each
service exposes an arbitrary number of supported types and these are available in the
<<metadata,metadata>>.
* `javaVersion`: the JVM language level (e.g. `1.8`).
* `bootVersion`: the platform version to use (e.g. `2.1.0.RELEASE`).
* `language`: the programming language to use (e.g. `java`).
* `packaging`: the packaging of the project (e.g. `jar`).
* `applicationName`: the name of the application class (inferred by the `name`
attribute by default).
* `baseDir`: the name of the base directory to create in the archive. By default, the
project is stored in the root.
[TIP]
====
You can "curl" an instance to get a usage page with examples (try
`curl https://start.spring.io`)
====
This command generates an `another-project` directory holding a Gradle web-based
Groovy project using the actuator:
[source,bash]
----
$ curl https://start.spring.io/starter.tgz -d dependencies=web,actuator \
-d language=groovy -d type=gradle-project -d baseDir=another-project | tar -xzvf -
----
NOTE: The `/starter.tgz` endpoint offers the same feature as `/starter.zip` but
generates a compressed tarball instead.
You could use this infrastructure to create your own client since the project is
generated via a plain HTTP call.
[[metadata]]
== Service metadata
The service metadata is used by all clients to know which values they should expose for
the standard attributes of a project. For instance, a custom version can specify that the
default `groupId` is `com.example.acme`. You can grab the metadata on the root endpoint
with the appropriate `Accept` header:
[source,bash]
----
$ curl -H 'Accept: application/json' https://start.spring.io
----
NOTE: As stated above, if you use `curl` without an accept header, you'll retrieve a
human readable text version of the metadata.
`HTTPie` is also supported:
[source,bash]
----
$ http https://start.spring.io Accept:application/json
----
The metadata basically lists the _capabilities_ of the service, that is the available
options for all request parameters (`dependencies`, `type`, `bootVersion`, etc.) A client
to the service uses that information to initialize the select options and the tree of
available dependencies.
The metadata also lists the default values for simple _text_ parameter (i.e. the
default `name` for the project).
NOTE: More details about the structure of the metadata are
{docs}/html/#metadata-format[available in the documentation].
== Running your own instance
You can easily run your own instance. The `initializr-web` modules uses Spring Boot
so when it is added to a project, it will trigger the necessary auto-configuration to
@@ -165,9 +74,6 @@ deploy the service.
The `initializr-service-sample` showcases a basic custom instance with dedicated metadata.
If you want to run our instance at https://start.spring.io, refer to
https://github.com/spring-io/start.spring.io#run-app[run the default instance locally].
[[build]]
== Building from Source

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

@@ -224,17 +224,18 @@ this makes sure to add the Kotlin-specific jackson module for better interoperab
[[create-instance]]
== Creating your own instance
NOTE: This walkthrough of how to create your own service assumes that the service will be
used for creating Spring Boot projects which is the why `initializr-generator-spring` jar
is included.
This section describes how one can create a custom service.
Spring Initializr provides a Bill of Materials (BOM) so that you don't have to worry about
versions. You can generate a project for your own instance on https://start.spring.io.
Create a new project with the `web` dependency and add the following dependencies and BOM:
The first step is to create a new project for your instance and add the following to
the build:
[source,xml,indent=0,subs="verbatim,attributes"]
----
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>io.spring.initializr</groupId>
<artifactId>initializr-web</artifactId>
@@ -262,6 +263,7 @@ Or if you are using Gradle:
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
----
implementation("org.springframework.boot:spring-boot-starter-web")
implementation("io.spring.initializr:initializr-web")
implementation("io.spring.initializr:initializr-generator-spring")
@@ -272,6 +274,9 @@ dependencyManagement {
}
----
NOTE: It is assumed that the custom instance will be used to generate Spring Boot-based
projects using the conventions provided by the `initializr-generator-spring` module.
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
@@ -282,8 +287,8 @@ we will configure those basic settings.
====
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`.
format that is more readable for such structure. If you agree, go ahead and create an
`application.yml` in `src/main/resources`.
====
@@ -825,6 +830,69 @@ below, in order of decreasing weight, if they have one (unweighted dependencies
last).
[[configuration-access]]
== Generating a Project using the Web Endpoints
To discover the available options of a particular instance, simply "curl it". Assuming
that an instance is running on your machine on the default port, invoke the following:
[indent=0]
----
$ curl http://localhost:8080
----
Alternatively, if you prefer `HTTPie`, you can discover the available options as follows:
[indent=0]
----
$ http http://localhost:8080
----
The result is a textual representation of the capabilities of the service that are split
in three sections:
First, a table that describes the <<create-instance-types,available project types>>.
Then, a table that describes the <<initializr-generator-project,available parameters>>.
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
`2.3.5.RELEASE`, using the `web` and `devtools` dependencies (remember, those two ids are
displayed in the capabilities of the service):
[source]
----
$ curl http://localhost:8080/starter.zip -d dependencies=web,devtools \
-d bootVersion=2.3.5.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 impact on the
name of the project)
The exact same project can be generated using the `http` command as well:
[source]
----
$ http https://localhost:8080/starter.zip dependencies==web,devtools \
bootVersion==2.3.5.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.
[[configuration-howto]]
== '`How-to`' guides

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

@@ -14,8 +14,8 @@ 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
* <<introduction.adoc#introduction>>: This section provides an introduction to the library and how one
can interact with the service to generate a project.
* <<configuration-guide.adoc#configuration-guide>>: This section covers creating your own
instance of Spring Initializr using the jars as libraries in your own app.

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

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 777 KiB

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

@@ -31,7 +31,7 @@ Stéphane Nicoll; Dave Syer; Madhura Bhave
// ======================================================================================
include::documentation-overview.adoc[]
include::user-guide.adoc[]
include::introduction.adoc[]
include::configuration-guide.adoc[]
include::api-guide.adoc[]
// ======================================================================================

41
initializr-docs/src/main/asciidoc/introduction.adoc Normal file
View File

@@ -0,0 +1,41 @@
[[introduction]]
= Introduction
[partintro]
--
This is a gentle introduction to what Spring Initializr can do. You'll find the various
ways you can interact with a Spring Initializr service and get a better insight at what
you can do with it.
The service allows you to generate JVM-based 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.
--
== Project Metadata
Spring Initializr exposes a number of endpoints that can be used to generate a JVM-based
project. You can easily <<configuration-guide.adoc#create-instance,create your own
instance>> by providing the metadata of various core concepts.
Based on the metadata and a list of contributors, a
<<configuration-guide.adoc#initializr-generator-project,project generation engine>> is
available to generate the actual project's assets. The result of the generation could be
a directory with a project or any other content.
== Web Endpoints
This library can be used in a web application to expose a number of endpoints that are
used to handle project generation. The main entry point for the service is its metadata
endpoint, available at the root of the context. It is used by various clients to determine
the available options and present them to the user, if possible.
The metadata endpoint also lists the type of projects that can be generated and how the
service can trigger them.
== Supported Clients
Out-of-the-box, a custom instance handles command-line requests using `cURL` or `HTTPie`.
Spring Initializr is also supported in various IDEs, check the documentation of your
favourite IDE for more details.
NOTE: Spring Initializr does not provide a Web UI to interact with the service.

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

@@ -23,7 +23,7 @@ The following versions are supported:
* `v2.1` support compatibility range and dependencies links
* `v2.2` (current) support for V1 and V2 version formats.
This is an example output for a service running at `https://start.spring.io`:
This is an example output for a service running at `start.example.com`:
.request
include::{snippets}/metadataWithCurrentAcceptHeader/http-request.adoc[]

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

@@ -1,247 +0,0 @@
[[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 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
which is the recommended way to add dependencies to a Spring Boot application.
--
[[getting-started]]
== Getting Started
Let's create a 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 below. 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:
image::web-selected.png[Browser,1200, 720]
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:
```
.gitignore
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, 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`).
[[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:
* *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*: the Java version to use
[[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 choose a milestone or snapshot 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 search for a dependency that you know to be available and you get a disabled
panel, it indicates that you cannot use it with the currently selected Spring Boot
version;
```
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.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.2.0.RELEASE
```
That version range means the dependency is not available with the selected Spring Boot
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
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. 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
```
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`)
* Packaging: `packaging` (`jar`, `war`)
* Group: `groupId`
* Artifact: `artifactId`
* Name: `name`
* Description: `description`
* Package Name: `packageName`
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: 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
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 https://start.spring.io` on the command-line (or alternatively
`http https://start.spring.io` if you prefer to use `HTTPie`).
The result is a textual representation of the capabilities of the service that are split
in three sections:
First, a table that describes the available project 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
`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.9.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 impact 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==2.1.9.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 https://plugins.netbeans.org/plugin/67888/nb-springboot[NB
SpringBoot plugin])
* Microsoft VSCode
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].

6
initializr-web/src/test/java/io/spring/initializr/web/AbstractInitializrControllerIntegrationTests.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2012-2019 the original author or authors.
* Copyright 2012-2020 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -38,10 +38,10 @@ import org.springframework.test.context.TestExecutionListeners.MergeMode;
@TestExecutionListeners(mergeMode = MergeMode.MERGE_WITH_DEFAULTS,
listeners = MockMvcClientHttpRequestFactoryTestExecutionListener.class)
@AutoConfigureMockMvc
@AutoConfigureRestDocs(outputDir = "target/snippets", uriPort = 80, uriHost = "start.spring.io")
@AutoConfigureRestDocs(outputDir = "target/snippets", uriPort = 80, uriHost = "start.example.com")
public abstract class AbstractInitializrControllerIntegrationTests extends AbstractInitializrIntegrationTests {
protected String host = "start.spring.io";
protected String host = "start.example.com";
@Autowired
private MockMvcClientHttpRequestFactory requests;

4
initializr-web/src/test/java/io/spring/initializr/web/controller/CommandLineMetadataControllerSslIntegrationTests.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2012-2019 the original author or authors.
* Copyright 2012-2020 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -37,7 +37,7 @@ public class CommandLineMetadataControllerSslIntegrationTests extends AbstractIn
void forceSsl() {
ResponseEntity<String> response = invokeHome("curl/1.2.4", "*/*");
String body = response.getBody();
assertThat(body).as("Must force https").contains("https://start.spring.io/");
assertThat(body).as("Must force https").contains("https://start.example.com/");
assertThat(body).as("Must force https").doesNotContain("http://");
}