Add bindings props to generated docs

Fixes #362

buildSrc/src/main/java/org/springframework/pulsar/gradle/docs/configprops/Snippets.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2022 the original author or authors.
+ * Copyright 2012-2023 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.
@@ -35,6 +35,7 @@ import org.gradle.api.file.FileCollection;
  *
  * @author Brian Clozed
  * @author Phillip Webb
+ * @author Chris Bono
  */
 class Snippets {
 
@@ -76,13 +77,24 @@ class Snippets {
 			});
 			table.addRow(row);
 		});
-		snippet.forEachPrefix((prefix) -> {
-			remaining.stream().filter((candidate) -> candidate.startsWith(prefix)).forEach((name) -> {
-				if (added.add(name)) {
-					table.addRow(new SingleRow(snippet, this.properties.get(name)));
+
+		snippet.forEachPrefix((prefix) ->
+				remaining.stream().filter((p) -> p.startsWith(prefix) &&
+						!DocsOnlyConfigurationProperty.isDocsOnlyProp(p)).forEach((name) -> {
+			if (added.add(name)) {
+				table.addRow(new SingleRow(snippet, this.properties.get(name)));
+
+				// Handle any "docs only" props
+				if (name.equals("spring.cloud.stream.pulsar.bindings")) {
+					// TODO if sourceType is Map<K,V> then look for docs only props
+					this.properties.stream()
+							.filter((p) -> DocsOnlyConfigurationProperty.isDocsOnlyPropUnderPrefix(p, name))
+							.filter((p) -> added.add(p.getName()))
+							.map(DocsOnlyConfigurationProperty::fromConfigProp)
+							.forEach((p) -> table.addRow(new SingleRow(snippet, p)));
 				}
-			});
-		});
+			}
+		}));
 		Asciidoc asciidoc = getAsciidoc(snippet, table);
 		writeAsciidoc(outputDirectory, snippet, asciidoc);
 		return added;
@@ -128,4 +140,42 @@ class Snippets {
 		}
 	}
 
+	static class DocsOnlyConfigurationProperty extends ConfigurationProperty {
+
+		private static final String DOCS_ONLY_TOKEN = ".for-docs-only";
+
+		private final String displayName;
+
+		private DocsOnlyConfigurationProperty(String name, String displayName, String type,
+				Object defaultValue, String description, boolean deprecated) {
+			super(name, type, defaultValue, description, deprecated);
+			this.displayName = displayName;
+		}
+
+		@Override
+		String getDisplayName() {
+			return this.displayName;
+		}
+
+		static DocsOnlyConfigurationProperty fromConfigProp(ConfigurationProperty prop) {
+			var propNewName = prop.getName().replace(DOCS_ONLY_TOKEN, ".z");
+			var propDisplayName = prop.getName().replace(DOCS_ONLY_TOKEN, ".*");
+			return new DocsOnlyConfigurationProperty(
+					propNewName,
+					propDisplayName,
+					prop.getType(),
+					prop.getDefaultValue(),
+					prop.getDescription(),
+					prop.isDeprecated());
+		}
+
+		static boolean isDocsOnlyProp(String propName) {
+			return propName.contains(DOCS_ONLY_TOKEN);
+		}
+
+		static boolean isDocsOnlyPropUnderPrefix(ConfigurationProperty configProp, String prefix) {
+			return configProp.getName().startsWith(prefix + DOCS_ONLY_TOKEN);
+		}
+
+	}
 }

spring-pulsar-spring-cloud-stream-binder/src/main/java/org/springframework/pulsar/spring/cloud/stream/binder/properties/PulsarBinderConfigurationProperties.java

@@ -23,7 +23,9 @@ import org.springframework.pulsar.autoconfigure.ConsumerConfigProperties;
 import org.springframework.pulsar.autoconfigure.ProducerConfigProperties;
 
 /**
- * {@link ConfigurationProperties} for Pulsar binder configuration.
+ * {@link ConfigurationProperties @ConfigurationProperties} for the Pulsar binder.
+ * <p>
+ * These properties are applied at the binder level (to all bindings).
  *
  * @author Soby Chacko
  * @author Chris Bono
@@ -31,9 +33,15 @@ import org.springframework.pulsar.autoconfigure.ProducerConfigProperties;
 @ConfigurationProperties(prefix = "spring.cloud.stream.pulsar.binder")
 public class PulsarBinderConfigurationProperties {
 
+	/**
+	 * Pulsar consumer specific binder-level properties (applied to all bindings).
+	 */
 	@NestedConfigurationProperty
 	private final ConsumerConfigProperties consumer = new ConsumerConfigProperties();
 
+	/**
+	 * Pulsar producer specific binder-level properties (applied to all bindings).
+	 */
 	@NestedConfigurationProperty
 	private final ProducerConfigProperties producer = new ProducerConfigProperties();
 

spring-pulsar-spring-cloud-stream-binder/src/main/java/org/springframework/pulsar/spring/cloud/stream/binder/properties/PulsarBindingProperties.java

@@ -16,12 +16,40 @@
 
 package org.springframework.pulsar.spring.cloud.stream.binder.properties;
 
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.boot.context.properties.NestedConfigurationProperty;
 import org.springframework.cloud.stream.binder.BinderSpecificPropertiesProvider;
 
+/**
+ * Container for Pulsar specific extended producer and consumer binding properties.
+ * <p>
+ * These properties are applied to individual bindings and will override any binder-level
+ * setting.
+ *
+ * <p>
+ * <em>NOTE:</em> This class is only referenced as a value in the
+ * {@link PulsarExtendedBindingProperties#getBindings() bindings map} and therefore, by
+ * default is not included in the generated configuration metadata. To get around this
+ * limitation it is annotated with {@code @ConfigurationProperties}. However, that is the
+ * only reason it is annotated and is not intended to be used directly.
+ *
+ * @author Soby Chacko
+ * @author Chris Bono
+ */
+@SuppressWarnings("ConfigurationProperties")
+@ConfigurationProperties("spring.cloud.stream.pulsar.bindings.for-docs-only")
 public class PulsarBindingProperties implements BinderSpecificPropertiesProvider {
 
+	/**
+	 * Pulsar consumer specific binding properties.
+	 */
+	@NestedConfigurationProperty
 	private PulsarConsumerProperties consumer = new PulsarConsumerProperties();
 
+	/**
+	 * Pulsar producer specific binding properties.
+	 */
+	@NestedConfigurationProperty
 	private PulsarProducerProperties producer = new PulsarProducerProperties();
 
 	public PulsarConsumerProperties getConsumer() {

spring-pulsar-spring-cloud-stream-binder/src/main/java/org/springframework/pulsar/spring/cloud/stream/binder/properties/PulsarExtendedBindingProperties.java

@@ -22,6 +22,16 @@ import org.springframework.boot.context.properties.ConfigurationProperties;
 import org.springframework.cloud.stream.binder.AbstractExtendedBindingProperties;
 import org.springframework.cloud.stream.binder.BinderSpecificPropertiesProvider;
 
+/**
+ * {@link ConfigurationProperties @ConfigurationProperties} for Pulsar binder specific
+ * extensions to the common binding properties.
+ * <p>
+ * These properties are applied to individual bindings and will override any binder-level
+ * settings.
+ *
+ * @author Soby Chacko
+ * @author Chris Bono
+ */
 @ConfigurationProperties("spring.cloud.stream.pulsar")
 public class PulsarExtendedBindingProperties extends
 		AbstractExtendedBindingProperties<PulsarConsumerProperties, PulsarProducerProperties, PulsarBindingProperties> {
@@ -33,6 +43,9 @@ public class PulsarExtendedBindingProperties extends
 		return DEFAULTS_PREFIX;
 	}
 
+	/**
+	 * Properties per individual binding name (e.g. 'mySink-in-0').
+	 */
 	@Override
 	public Map<String, PulsarBindingProperties> getBindings() {
 		return this.doGetBindings();

spring-pulsar-spring-cloud-stream-binder/src/main/resources/META-INF/additional-spring-configuration-metadata.json

@@ -0,0 +1,10 @@
+{
+  "groups": [],
+  "properties": [
+    {
+      "name": "spring.cloud.stream.pulsar.bindings",
+      "description": "Properties per individual binding name (e.g. 'mySink-in-0'). Replace the '*' ' with the name of your binding."
+    }
+  ],
+  "hints": []
+}