lsm/initializr
1
0
Fork 0
mirror of https://gitee.com/dcren/initializr.git synced 2026-08-10 11:13:34 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Polish readme

Browse Source
This commit is contained in:
Stephane Nicoll
2017-02-03 08:00:37 +01:00
parent f5fc9e488c
commit b584f3020e
1 changed files with 97 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

183
README.adoc
View File

@@ -1,39 +1,47 @@
= Spring Initializr image:https://badges.gitter.im/spring-io/initializr.svg[link="https://gitter.im/spring-io/initializr?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"] = Spring Initializr image:https://badges.gitter.im/spring-io/initializr.svg[link="https://gitter.im/spring-io/initializr?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"]
:wiki: https://github.com/spring-io/initializr/wiki
:boot-doc: http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle :boot-doc: http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle
:code: https://github.com/spring-io/initializr/blob/master :code: https://github.com/spring-io/initializr/blob/master
:docs: http://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference
Spring Initializr provides an extensible API to generate quickstart projects. It also Spring Initializr provides an extensible API to generate quickstart projects. It also
provides a configurable service: you can see our default instance at provides a configurable service: you can see our default instance at
link:https://start.spring.io[]. It provides a simple web UI to configure the project link: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. to generate and endpoints that you can use via plain HTTP.
Spring Initializr also exposes an endpoint that serves its Spring Initializr also exposes an endpoint that serves its metadata in a well-known
{wiki}/Metadata-format[metadata] in a well-known format to allow third-party format to allow third-party clients to provide the necessary assistance.
clients to provide the necessary assistance.
Finally, Initializr offers a configuration structure to define all the aspects related Finally, Initializr offers a configuration structure to define all the aspects
to the project to generate: list of dependencies, supported java and boot versions, etc. Check related to the project to generate: list of dependencies, supported java and boot
the {code}/initializr-service/src/main/resources/application.yml[configuration of our instance] for an example. Such versions, etc. Check
configuration is {wiki}/Configuration-format[also described in details on the wiki]. the {code}/initializr-service/src/main/resources/application.yml[configuration of our
instance] for an example. Such configuration is also described in details in the
documentation.
NOTE: We use the continuous deployment technique to manage our instance; check the NOTE: We use the continuous deployment technique to manage our instance; check the
https://github.com/spring-io/initializr/milestones[milestones page] for an overview of changes https://github.com/spring-io/initializr/milestones[milestones page] for an overview
of changes
== Installation and Getting Started
The {docs}/htmlsingle/[reference documentation] is published in
{docs}/htmlsingle/[HTML], {docs}/pdf/spring-initializr-reference.pdf[PDF] and
{docs}/epub/spring-initializr-reference.epub[EPUB] formats.
== Modules == Modules
Spring Initializr has the following modules: Spring Initializr has the following modules:
* `initializr-generator`: standalone project generation library that can be reused in * `initializr-generator`: standalone project generation library that can be reused
many environments (including embedded in your own project) in many environments (including embedded in your own project)
* `initializr-web`: REST endpoints and web interface * `initializr-web`: REST endpoints and web interface
* `initializr-actuator`: optional module to provide statistics and metrics on project * `initializr-actuator`: optional module to provide statistics and metrics on project
generation generation
* `initializr-docs`: documentation
`initializr-service` is an additional module that represents the production instance that `initializr-service` is an additional module that represents the production instance
is available at link:https://start.spring.io[]. It is not enabled by default but you can that is available at link:https://start.spring.io[]. It is not enabled by default but
enable the `full` profile in your IDE to easily run it locally. you can enable the `full` profile in your IDE to easily run it locally.
== Supported interfaces == Supported interfaces
@@ -42,18 +50,19 @@ Spring Initializr can be used as follows:
* With your browser (i.e. link:https://start.spring.io[]) * With your browser (i.e. link:https://start.spring.io[])
* In your IDE if you are using STS, IntelliJ IDEA Ultimate or NetBeans (with * In your IDE if you are using STS, IntelliJ IDEA Ultimate or NetBeans (with
https://github.com/AlexFalappa/nb-springboot[this plugin]) https://github.com/AlexFalappa/nb-springboot[this plugin])
* On the command-line with {boot-doc}/#cli-init[the Spring Boot CLI] or simply with `cURL` or `HTTPie` * On the command-line with {boot-doc}/#cli-init[the Spring Boot CLI] or simply with
`cURL` or `HTTPie`
[TIP] [TIP]
==== ====
You can "curl" an instance to get a usage page with examples (try `curl start.spring.io`) You can "curl" an instance to get a usage page with examples (try
`curl start.spring.io`)
==== ====
== Generating a project == Generating a project
If you click on "Generate Project" on the web ui of our instance, it will download a
If you click on "Generate Project" on the web ui of our instance, it will download a project project archive with a Maven-based project and the necessary infrastructure to start
archive with a Maven-based project and the necessary infrastructure to start a basic Spring a basic Spring Boot app.
Boot app.
You could achieve the same result with a simple `curl` command You could achieve the same result with a simple `curl` command
@@ -62,30 +71,32 @@ You could achieve the same result with a simple `curl` command
$ curl https://start.spring.io/starter.zip -o demo.zip $ curl https://start.spring.io/starter.zip -o demo.zip
---- ----
The web ui exposes a bunch of options that you can configure. These are mapped to the following The web ui exposes a bunch of options that you can configure. These are mapped to the
request attributes: following request attributes:
* Basic information for the generated project: `groupId`, `artifactId`, `version`, `name`, * Basic information for the generated project: `groupId`, `artifactId`, `version`,
`description` and `packageName` `name`, `description` and `packageName`
** The `name` attribute is also used to generate a default application name. The logic is ** The `name` attribute is also used to generate a default application name. The
that the name of the application is equal to the `name` attribute with an `Application` logic is that the name of the application is equal to the `name` attribute with an
suffix (unless said suffix is already present). Of course, if the specified name contains `Application` suffix (unless said suffix is already present). Of course, if the
an invalid character for a java identifier, `Application` is used as fallback. specified name contains an invalid character for a java identifier, `Application` is
** The `artifactId` attribute not only defines the identifier of the project in the build but used as fallback.
also the name of the generated archive. ** The `artifactId` attribute not only defines the identifier of the project in the
* `dependencies` (or `style`): the identifiers of the dependencies to add to the project. Such build but also the name of the generated archive.
identifiers are defined through configuration and are exposed in the <<metadata,metadata>>. * `dependencies` (or `style`): the identifiers of the dependencies to add to the
* `type`: the _kind_ of project to generate (e.g. `maven-project`). Again, each service project. Such identifiers are defined through configuration and are exposed in the
exposes an arbitrary number of supported types and these are available 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>>. <<metadata,metadata>>.
* `javaVersion`: the language level (e.g. `1.8`). * `javaVersion`: the language level (e.g. `1.8`).
* `bootVersion`: the Spring Boot version to use (e.g. `1.2.0.RELEASE`). * `bootVersion`: the Spring Boot version to use (e.g. `1.2.0.RELEASE`).
* `language`: the programming language to use (e.g. `java`). * `language`: the programming language to use (e.g. `java`).
* `packaging`: the packaging of the project (e.g. `jar`). * `packaging`: the packaging of the project (e.g. `jar`).
* `applicationName`: the name of the application class (inferred by the `name` attribute by * `applicationName`: the name of the application class (inferred by the `name`
default). attribute by default).
* `baseDir`: the name of the base directory to create in the archive. By default, the project * `baseDir`: the name of the base directory to create in the archive. By default, the
is stored in the root. project is stored in the root.
This command generates an `another-project` directory holding a Gradle web-based This command generates an `another-project` directory holding a Gradle web-based
Groovy project using the actuator: Groovy project using the actuator:
@@ -96,27 +107,27 @@ $ curl https://start.spring.io/starter.tgz -d dependencies=web,actuator \
-d language=groovy -d type=gradle-project -d baseDir=another-project | tar -xzvf - -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 NOTE: The `/starter.tgz` endpoint offers the same feature as `/starter.zip` but
a compressed tarball instead. generates a compressed tarball instead.
You could use this infrastructure to create your own client since the project is generated You could use this infrastructure to create your own client since the project is
via a plain HTTP call. generated via a plain HTTP call.
[[customize-form]] [[customize-form]]
== Customize form inputs == Customize form inputs
You can share or bookmark URLs that will automatically customize form inputs. For instance, You can share or bookmark URLs that will automatically customize form inputs. For
the following URL from the default instance uses `groovy` by default and set the name instance, the following URL from the default instance uses `groovy` by default and
to `Groovy Sample`: set the name to `Groovy Sample`:
[source,bash] [source,bash]
---- ----
https://start.spring.io/#!language=groovy&name=Groovy%20Sample https://start.spring.io/#!language=groovy&name=Groovy%20Sample
---- ----
The following hashbang parameters are supported: `type`, `groupId`, `artifactId`, `name`, The following hashbang parameters are supported: `type`, `groupId`, `artifactId`,
`description`, `packageName`, `packaging`, `javaVersion` and `language`. Review the section `name`, `description`, `packageName`, `packaging`, `javaVersion` and `language`.
above for a description of each of them. Review the section above for a description of each of them.
[[metadata]] [[metadata]]
== Service metadata == Service metadata
@@ -129,39 +140,38 @@ third-party clients. You can grab the metadata by _curling_ the root
$ curl -H 'Accept: application/json' https://start.spring.io $ 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 NOTE: As stated above, if you use `curl` without an accept header, you'll retrieve a
readable text version of the metadata. `HTTPie` is also supported: human readable text version of the metadata. `HTTPie` is also supported:
[source,bash] [source,bash]
---- ----
$ http https://start.spring.io Accept:application/json $ http https://start.spring.io Accept:application/json
---- ----
The metadata basically lists the _capabilities_ of the service, that is the available The metadata basically lists the _capabilities_ of the service, that is the available
options for all request parameters (`dependencies`, `type`, `bootVersion`, etc.) The web options for all request parameters (`dependencies`, `type`, `bootVersion`, etc.) The
UI uses that information to initialize the select options and the tree of available web UI uses that information to initialize the select options and the tree of
dependencies. available dependencies.
The metadata also lists the default values for simple _text_ parameter (i.e. the default The metadata also lists the default values for simple _text_ parameter (i.e. the
`name` for the project). default `name` for the project).
NOTE: More details about the structure of the metadata are {wiki}/Metadata-format[available NOTE: More details about the structure of the metadata are
on the wiki]. {docs}/htmlsingle/#metadata-format[available in the documentation].
== Running your own instance == Running your own instance
You can easily run your own instance. The `initializr-web` modules uses Spring Boot so when it You can easily run your own instance. The `initializr-web` modules uses Spring Boot
is added to a project, it will trigger the necessary auto-configuration to deploy the service. so when it is added to a project, it will trigger the necessary auto-configuration to
deploy the service.
You first need to create or update your configuration to define the necessary attributes that You first need to create or update your configuration to define the necessary
your instance will use. Again, check the wiki for a {wiki}/Configuration-format[description attributes that your instance will use. Again, check the documentation for a
of the configuration] and {code}/initializr-service/application.yml[review our own config] for {docs}/htmlsingle/#configuratio -format[description of the configuration] and
a sample. {code}/initializr-service/application.yml[review our own config] for a sample.
You can integrate the library in a traditional Java-based project or by writing the super-simple You can integrate the library in a traditional Java-based project or by writing the
script below super-simple script below:
[source,groovy] [source,groovy]
---- ----
@@ -172,11 +182,11 @@ package org.acme.myapp
class YourInitializrApplication { } class YourInitializrApplication { }
---- ----
NOTE: Spring Initializr is not available on Maven central yet so you will have to build NOTE: Spring Initializr is not available on Maven central yet so you will have to
it <<build,from source>> in order to use it in your own environment. build it <<build,from source>> in order to use it in your own environment.
Once you have created that script (`my-instance.groovy`), place your configuration in the same Once you have created that script (`my-instance.groovy`), place your configuration
directory and simply execute this command to start the service: in the same directory and simply execute this command to start the service:
[source,bash] [source,bash]
---- ----
@@ -209,7 +219,8 @@ If you want to run the smoke tests using Geb, you need to enable the
$ mvn verify -PsmokeTests $ mvn verify -PsmokeTests
---- ----
If you want to build both the library and the service, you can enable the `full` profile: If you want to build both the library and the service, you can enable the `full`
profile:
[indent=0] [indent=0]
---- ----
@@ -220,8 +231,8 @@ If you want to build both the library and the service, you can enable the `full`
[[run-app]] [[run-app]]
=== Running the app locally === Running the app locally
Once you have <<building, built the library>>, you can easily start the app as any other Once you have <<building, built the library>>, you can easily start the app as any
Spring Boot app from the `initializr-service` directory: other Spring Boot app from the `initializr-service` directory:
[indent=0] [indent=0]
---- ----
@@ -232,18 +243,18 @@ Spring Boot app from the `initializr-service` directory:
[[run-ide]] [[run-ide]]
=== Running the app in an IDE === Running the app in an IDE
You should be able to import the projects into your IDE with no You should be able to import the projects into your IDE with no problems (STS with
problems (STS with the m2e Groovy compiler support or IntelliJ IDEA the m2e Groovy compiler support or IntelliJ IDEA definitely work). Once there you can
definitely work). Once there you can run the `initializr-service` from run the `initializr-service` from its main method, debug it, and it will reload if
its main method, debug it, and it will reload if you make changes to you make changes to other modules. (You may need to manually enable the "full"
other modules. (You may need to manually enable the "full" profile.) profile.) This is the recommended way to operate while you are developing the
This is the recommended way to operate while you are developing the
application, especially the UI. application, especially the UI.
## Deploying to Cloud Foundry ## Deploying to Cloud Foundry
If you are on a Mac and using http://brew.sh/[homebrew], install the Cloud Foundry CLI: If you are on a Mac and using http://brew.sh/[homebrew], install the Cloud Foundry
CLI:
[indent=0] [indent=0]
---- ----
@@ -253,11 +264,11 @@ If you are on a Mac and using http://brew.sh/[homebrew], install the Cloud Found
Alternatively, download a suitable binary for your platform from Alternatively, download a suitable binary for your platform from
https://console.run.pivotal.io/tools[Pivotal Web Services]. https://console.run.pivotal.io/tools[Pivotal Web Services].
You should ensure that the application name and URL (name and host values) are suitable for You should ensure that the application name and URL (name and host values) are
your environment before running `cf push`. suitable for your environment before running `cf push`.
First, make sure that you have <<building, built the library>>, then make sure first that First, make sure that you have <<building, built the library>>, then make sure first
the jar has been created: that the jar has been created:
[indent=0] [indent=0]
---- ----