diff --git a/README.adoc b/README.adoc index 7022de09..a3a90df0 100644 --- a/README.adoc +++ b/README.adoc @@ -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 -<>. -* `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 -<>. -* `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 diff --git a/initializr-docs/src/main/asciidoc/configuration-guide.adoc b/initializr-docs/src/main/asciidoc/configuration-guide.adoc index d426bae0..2e12eedb 100644 --- a/initializr-docs/src/main/asciidoc/configuration-guide.adoc +++ b/initializr-docs/src/main/asciidoc/configuration-guide.adoc @@ -224,25 +224,26 @@ 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"] ---- - io.spring.initializr - initializr-web - - - io.spring.initializr - initializr-generator-spring - + org.springframework.boot + spring-boot-starter-web + + + io.spring.initializr + initializr-web + + + io.spring.initializr + initializr-generator-spring + @@ -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 <>. + +Then, a table that describes the <>. + +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 diff --git a/initializr-docs/src/main/asciidoc/documentation-overview.adoc b/initializr-docs/src/main/asciidoc/documentation-overview.adoc index 1772f47a..c367b541 100644 --- a/initializr-docs/src/main/asciidoc/documentation-overview.adoc +++ b/initializr-docs/src/main/asciidoc/documentation-overview.adoc @@ -14,8 +14,8 @@ dependencies and versions. The documentation is roughly divided into three parts: -* <>: This section is about how to use our default instance of -Spring Initializr which is available at https://start.spring.io +* <>: This section provides an introduction to the library and how one +can interact with the service to generate a project. * <>: This section covers creating your own instance of Spring Initializr using the jars as libraries in your own app. diff --git a/initializr-docs/src/main/asciidoc/images/web-selected.png b/initializr-docs/src/main/asciidoc/images/web-selected.png deleted file mode 100644 index 2de3eb9a..00000000 Binary files a/initializr-docs/src/main/asciidoc/images/web-selected.png and /dev/null differ diff --git a/initializr-docs/src/main/asciidoc/index.adoc b/initializr-docs/src/main/asciidoc/index.adoc index d51b869c..8e92ed51 100644 --- a/initializr-docs/src/main/asciidoc/index.adoc +++ b/initializr-docs/src/main/asciidoc/index.adoc @@ -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[] // ====================================================================================== diff --git a/initializr-docs/src/main/asciidoc/introduction.adoc b/initializr-docs/src/main/asciidoc/introduction.adoc new file mode 100644 index 00000000..82d71c9a --- /dev/null +++ b/initializr-docs/src/main/asciidoc/introduction.adoc @@ -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 <> by providing the metadata of various core concepts. + +Based on the metadata and a list of contributors, a +<> 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. + diff --git a/initializr-docs/src/main/asciidoc/metadata-format.adoc b/initializr-docs/src/main/asciidoc/metadata-format.adoc index 35a6b25e..309a9fb0 100644 --- a/initializr-docs/src/main/asciidoc/metadata-format.adoc +++ b/initializr-docs/src/main/asciidoc/metadata-format.adoc @@ -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[] diff --git a/initializr-docs/src/main/asciidoc/user-guide.adoc b/initializr-docs/src/main/asciidoc/user-guide.adoc deleted file mode 100644 index 9feb4903..00000000 --- a/initializr-docs/src/main/asciidoc/user-guide.adoc +++ /dev/null @@ -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]. diff --git a/initializr-web/src/test/java/io/spring/initializr/web/AbstractInitializrControllerIntegrationTests.java b/initializr-web/src/test/java/io/spring/initializr/web/AbstractInitializrControllerIntegrationTests.java index db56131f..c9909077 100755 --- a/initializr-web/src/test/java/io/spring/initializr/web/AbstractInitializrControllerIntegrationTests.java +++ b/initializr-web/src/test/java/io/spring/initializr/web/AbstractInitializrControllerIntegrationTests.java @@ -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; diff --git a/initializr-web/src/test/java/io/spring/initializr/web/controller/CommandLineMetadataControllerSslIntegrationTests.java b/initializr-web/src/test/java/io/spring/initializr/web/controller/CommandLineMetadataControllerSslIntegrationTests.java index 9131898b..48a115b2 100644 --- a/initializr-web/src/test/java/io/spring/initializr/web/controller/CommandLineMetadataControllerSslIntegrationTests.java +++ b/initializr-web/src/test/java/io/spring/initializr/web/controller/CommandLineMetadataControllerSslIntegrationTests.java @@ -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 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://"); }