From 4291ab97f5eba0c6f4ace0f8446d44d254986258 Mon Sep 17 00:00:00 2001 From: Stephane Nicoll Date: Tue, 17 Nov 2020 14:30:11 +0100 Subject: [PATCH] Polish --- .../main/asciidoc/configuration-format.adoc | 182 ------------------ .../src/main/asciidoc/metadata-format.adoc | 1 + .../src/main/asciidoc/using-the-stubs.adoc | 1 + 3 files changed, 2 insertions(+), 182 deletions(-) delete mode 100644 initializr-docs/src/main/asciidoc/configuration-format.adoc diff --git a/initializr-docs/src/main/asciidoc/configuration-format.adoc b/initializr-docs/src/main/asciidoc/configuration-format.adoc deleted file mode 100644 index e23d3c29..00000000 --- a/initializr-docs/src/main/asciidoc/configuration-format.adoc +++ /dev/null @@ -1,182 +0,0 @@ -[[configuration-format]] -# Configuration Format -This section describes the configuration structure that is used by Spring initializr. -The metadata provided through configuration are driving the options exposed by a -particular instance and <>. - -The configuration is split in several sections: - -* An `env` section used to provide various global settings. -* A `dependencies` section lists the available dependencies. This is the most -important section of the service as it defines the "libraries" that the user can -choose. -* The `groupId`, `artifactId`, `version`, `name`, `description` and `packageName` -provide default values for these project settings. -* The `types`, `packagings`, `javaVersions`, `languages` and `bootVersions` provide -the list of available option for each setting and which one is the default. - - - -## Env section -TIP: Check {sc-initializr-generator}/metadata/InitializrConfiguration.java#L142[the code] -for a full list of the available configuration options. - -The `env` element defines environment option that the service uses: - -* `artifactRepository`: the URL of the (maven) repository that should be used to -download the Spring Boot CLI distribution bundle. This is only used by the `/spring` -endpoint at the moment. -* `springBootMetadataUrl` the URL of the resource that provides the list of available -Spring Boot versions. -* `forceSsl`: a boolean flag that determines if we should redirect browser to `https` when -browsing via `http`. Also force the use of `https` in all links. This is not enabled by -default to ease local use case but should be enabled in production. -* `fallbackApplicationName`: the name of the _default_ application. Application names -are generated based on the project's name. However, some user input may result in an -invalid identifier for a Java class name for instance. -* `invalidApplicationNames`: a fixed list of invalid application names. If a project -generation uses one of these names, the fallback is used instead. -* `invalidPackageNames`: a fixed list of invalid package names. If a project -generation uses one of these names, the default is used instead. -* `googleAnalyticsTrackingCode`: the Google Analytics code to use. If this is set, -Google analytics is automatically enabled. -* `kotlin`: kotlin-specific settings. For now, only the kotlin version to use can be -configured and is a mandatory option if Kotlin is enabled. -* `maven`: maven-specified settings. A custom maven parent POM can be defined and -whether or not the `spring-boot-dependencies` BOM should be automatically added to -the project. - -If some of your dependencies require a custom Bill of Materials (BOM) and/or a custom -repository, you can add them here and use the id as a reference. For instance, let's -say that you want to integrate with library `foo` and it requires a `foo-bom` and a -`foo-repo`. You can configure things as follows: - -```yml -initializr: - env: - boms: - foo-bom: - groupId: com.example - artifactId: foo-bom - version: 1.2.3 - repositories: - foo-repo: - name: foo-release-repo - url: https://repo.example.com/foo - snapshotsEnabled: false -``` - -You can then use the `foo-bom` and `foo-repo` in a "dependency" or "dependency group" -section. - -NOTE: The `spring-milestones` and `spring-snapshots` repositories are available by -default. Please note that these are just references and won't impact the project -unless you choose a dependency that explicitly refer to a bom and/or repo by id. -Check the example below for more details. - -## Dependencies section - -The `dependencies` section allows you define a list of groups, each group having one -more `dependency`. A group gather dependencies that share a common characteristics -(i.e. all web-related dependencies for instance). - -A `dependency` has the following basic characteristics: - -* A mandatory identifier. If no further information is provided, a Spring Boot starer -with that id is assumed. -* A `name` and `description` used in the generated meta-data and the web ui. -* A `groupId` and `artifactId` to define the coordinates of the dependency. -* A `version` if Spring Boot does not already provide a dependency management for -that dependency. -* A `scope` (can be `compile`, `runtime`, `provided` or `test`). -* A `classifier` (if the dependency to use is classified, such as `test-jar`). -* The reference to a `bom` or a `repository` that must be added to the project once -that dependency is added. -* A `compatibilityRange` used to determine the platform versions that are compatible -with the dependency. -* Links to resources such as a guide or a reference doc section. - -TIP: Check {sc-initializr-generator}/metadata/Dependency.java[the code] for a full -list of the available configuration options. - -Here is the most basic dependency entry you could have - -[source,yaml,indent=0] ----- - initializr: - dependencies: - - name: Core - content: - - id: security - name: Security - description: Secure your application via spring-security ----- - -TIP: The `security` dependency is held within a group called "Core". - -This adds an option name `Security` with a tooltip showing the description above. If -a project is generated with that dependency, the -`org.springframework.boot:spring-boot-starter-security` dependency will be added to -the project. - -Let's now add a custom dependency that is not managed by Spring Boot and that only -work from Spring Boot `1.2.0.RELEASE` and onwards but should not be used in the 1.3 -lines and further for some reason. - -[source,yaml,indent=0] ----- - initializr: - dependencies: - - name: Core - content: - - id: my-lib-id - name: My lib - description: Secure your application via spring-security - groupId: com.example.foo - artifactId: foo-core - bom: foo-bom - repository: foo-repo - compatibilityRange: "[1.2.0.RELEASE,1.3.0.M1)" ----- - -If one selects this entry, the `com.example.foo:foo-core}` dependency will be added -and the Bill of Materials and repository for `foo` will be added automatically to -the project as well (see the "Env section" above for a reference to those -identifiers). Because the bom provides a dependency management for `foo-core` there -is no need to hard code the version in the configuration. - -The `compatibilityRange` syntax follows some simple rules: a square bracket "[" or "]" -denotes an inclusive end of the range and a round bracket "(" or ")" denotes an -exclusive end of the range. A range can also be unbounded by defining a a single -version. In the example above, the dependency will be available as from -`1.2.0.RELEASE` up to, not included, `1.3.0.M1` (which is the first milestone of the -1.3 line). - -### Dependency group - -A dependency group gather a set of dependencies as well as some common settings: -`bom`, `repository` and `compatibilityRange`. If one of them is set, it is applied for all -dependencies within that group. It is still possible to override a particular value -at the dependency level. - -## Other sections - -The other section defines the default and the list of available options in the web -UI. This also drives how the meta-data for your instance are generated and tooling -support is meant to react to that. - -For instance, if you want your groupId to default to `org.acme` and the -`javaVersions` to only be `1.8` and `11` you would write the following config: - -[source,yaml,indent=0] ----- - initializr: - groupId: - value: org.acme - javaVersions: - - id: 11 - default: false - - id: 1.8 - default: true ----- diff --git a/initializr-docs/src/main/asciidoc/metadata-format.adoc b/initializr-docs/src/main/asciidoc/metadata-format.adoc index 309a9fb0..5680a036 100644 --- a/initializr-docs/src/main/asciidoc/metadata-format.adoc +++ b/initializr-docs/src/main/asciidoc/metadata-format.adoc @@ -1,5 +1,6 @@ [[metadata-format]] = Metadata Format + This section describes the hal/json structure of the metadata exposed by the initializr. Such metadata can be used by third party clients to provide a list of options and default settings that can be used to request the creation of a project. diff --git a/initializr-docs/src/main/asciidoc/using-the-stubs.adoc b/initializr-docs/src/main/asciidoc/using-the-stubs.adoc index b282384f..1a7e121c 100644 --- a/initializr-docs/src/main/asciidoc/using-the-stubs.adoc +++ b/initializr-docs/src/main/asciidoc/using-the-stubs.adoc @@ -1,4 +1,5 @@ = Using the Stubs + Spring Initializr project publishes https://github.com/tomakehurst/wiremock[WireMock] stubs for all the JSON responses that are tested in the project. If you are writing a client for Spring Initializr