Allow binding of custom ProjectRequest

This commit allows a custom instance to easily bind incoming request
attributes to a custom ProjectRequest instance and map it to a custom
ProjectDescription as well.

Closes gh-990

initializr-docs/src/main/asciidoc/configuration-guide.adoc

@@ -1069,3 +1069,32 @@ expiration settings accordingly.
 |Cache templates that are used to generate projects.
 
 |===
+
+
+
+[[create-instance-advanced-config-custom-project-request]]
+=== Bind to custom project request
+Only attributes that are defined in the metadata can be bound to a `ProjectRequest` and
+ultimately made available in `ProjectDescription`. A custom instance may chose however to
+provide additional attributes. Please note that those attributes won't be supported by
+official clients (i.e. IDEs).
+
+The first step is to define a custom `ProjectRequest` with your additional attributes and
+create a custom `ProjectGenerationController` that binds to it:
+
+[source,java,indent=0,subs="verbatim,quotes,attributes"]
+----
+include::{code-examples}/doc/generator/project/CustomProjectGenerationController.java[tag=code]
+----
+
+If you inherit from `WebProjectRequest`, defaults can be automatically applied from the
+metadata as shown above but you may also chose to ignore that. If you define a `@Bean`
+for that controller, the auto-configuration will back-off and use yours instead.
+
+The next step is to make sure that those additional attributes are made available in the
+`ProjectGenerationContext`. The idiomatic way of doing this is to create your own
+interface that extends from `ProjectDescription` and expose your custom attributes. To
+make sure your view of `ProjectGeneration` is made available in the
+`ProjectGenerationContext`, a custom `ProjectRequestToDescriptionConverter` should be
+defined. When such a bean exists in the context it replaces the default that the
+auto-configuration provides.

initializr-docs/src/main/java/io/spring/initializr/doc/generator/project/CustomProjectGenerationController.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2012-2019 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.spring.initializr.doc.generator.project;
+
+import java.util.Map;
+
+import io.spring.initializr.metadata.InitializrMetadataProvider;
+import io.spring.initializr.web.controller.ProjectGenerationController;
+import io.spring.initializr.web.project.ProjectGenerationInvoker;
+
+/**
+ * Example of a custom {@link ProjectGenerationController}.
+ *
+ * @author Stephane Nicoll
+ */
+// tag::code[]
+public class CustomProjectGenerationController extends ProjectGenerationController<CustomProjectRequest> {
+
+	public CustomProjectGenerationController(InitializrMetadataProvider metadataProvider,
+			ProjectGenerationInvoker projectGenerationInvoker) {
+		super(metadataProvider, projectGenerationInvoker);
+	}
+
+	@Override
+	public CustomProjectRequest projectRequest(Map<String, String> headers) {
+		CustomProjectRequest request = new CustomProjectRequest();
+		request.getParameters().putAll(headers);
+		request.initialize(getMetadata());
+		return request;
+	}
+
+}
+// end::code[]

initializr-docs/src/main/java/io/spring/initializr/doc/generator/project/CustomProjectRequest.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2012-2019 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.spring.initializr.doc.generator.project;
+
+import io.spring.initializr.web.project.WebProjectRequest;
+
+/**
+ * A sample custom {@link WebProjectRequest}.
+ *
+ * @author Stephane Nicoll
+ */
+public class CustomProjectRequest extends WebProjectRequest {
+
+}