Fix config documentation generation script

[EricWittmann]

Summary

Fixes #6734 by refactoring the configuration documentation generator from a JBang script into a proper Maven module. With this change, if the java code fails to compile then the build will fail during the compile phase. Previously if there was a problem, the jbang exec could fail with logging info but without failing the build.

Issues Fixed

1. Compilation Error: The JBang script had syntax errors (orphaned periods on lines 199-201) causing compilation failures
2. Missing Documentation: New observability configuration properties from PR fix: REST metrics are not recorded for all expected requests #6592 + more config #6713 were not appearing in generated docs

Changes

Created docs/config-generator Maven Module

• New JAR module at docs/config-generator
• Proper package structure: io.apicurio.registry.docs
• Added comprehensive Javadoc explaining the tool's purpose and usage
• Dependencies: apicurio-registry-config-definitions and jandex

Refactored Build Process

• Uses exec-maven-plugin with exec:java goal (no shade plugin needed)
• Runs in process-classes phase after compilation
• Maven automatically handles classpath dependencies
• Simpler and more maintainable than JBang approach
• Works better in the IDE

Generated Documentation

The generated documentation now correctly includes all configuration properties, including:

• apicurio.metrics.rest.enabled
• apicurio.metrics.rest.path-filter-pattern
• apicurio.metrics.rest.method-tag-enabled
• apicurio.metrics.rest.path-tag-enabled
• apicurio.metrics.rest.explicit-status-codes-list

Additional Changes

• Added dependency-reduced-pom.xml to .gitignore for future use
• Fixed syntax errors in the generator code

Testing

Verified that:

• ✅ Module builds successfully
• ✅ Documentation is generated without errors
• ✅ Observability section appears in generated docs
• ✅ All five new REST metrics properties are documented
• ✅ Build works correctly from clean state

Migration Notes

The config generator is now built and executed as part of the docs/config-generator module. To generate documentation:

mvn clean install -pl :apicurio-registry-config-generator -DskipTests

To skip documentation generation:

mvn clean install -pl :apicurio-registry-config-generator -DskipTests -DskipDocsGen

[jsenko]

LGTM, not executing it through jbang will make this a bit more maintainable.

[Copilot]

Pull Request Overview

This PR refactors the documentation generation process by replacing the JBang-based script with a proper Maven module. The config generator is now a standalone module that uses the exec-maven-plugin to generate configuration documentation.

• Moved config generation from JBang script to a proper Maven module
• Cleaned up code formatting and added comprehensive JavaDoc documentation
• Updated generated documentation with new configuration properties

Reviewed Changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/pom.xml	Removed JBang plugin profile and added config-generator as a module
docs/config-generator/pom.xml	New Maven module for config generation with exec-maven-plugin
docs/config-generator/src/main/java/io/apicurio/registry/docs/GenerateAllConfigPartial.java	Converted from JBang script to proper Java class with package declaration and JavaDoc
docs/modules/ROOT/partials/getting-started/ref-registry-all-configs.adoc	Updated generated documentation with new properties and default values
.gitignore	Added dependency-reduced-pom.xml to ignore list

Comments suppressed due to low confidence (6)

docs/config-generator/src/main/java/io/apicurio/registry/docs/GenerateAllConfigPartial.java:54

• Missing generic type parameters for HashMap. Should be new HashMap<>() or new HashMap<String, Option>() to maintain type safety and follow Java best practices.
  docs/config-generator/src/main/java/io/apicurio/registry/docs/GenerateAllConfigPartial.java:1
• The generated documentation contains excessive whitespace between sentences (multiple spaces instead of single space). This appears to be a formatting issue in the source data or the generation logic. The description text should have consistent single-space separation between sentences.
  docs/config-generator/src/main/java/io/apicurio/registry/docs/GenerateAllConfigPartial.java:1
• The generated documentation contains excessive whitespace between sentences (multiple spaces instead of single space). This appears to be a formatting issue in the source data or the generation logic. The description text should have consistent single-space separation between sentences.
  docs/config-generator/src/main/java/io/apicurio/registry/docs/GenerateAllConfigPartial.java:1
• The generated documentation contains excessive whitespace between sentences (multiple spaces instead of single space). This appears to be a formatting issue in the source data or the generation logic. The description text should have consistent single-space separation between sentences.
  docs/config-generator/src/main/java/io/apicurio/registry/docs/GenerateAllConfigPartial.java:1
• The generated documentation contains excessive whitespace between sentences (multiple spaces instead of single space). This appears to be a formatting issue in the source data or the generation logic. The description text should have consistent single-space separation between sentences.
  docs/config-generator/src/main/java/io/apicurio/registry/docs/GenerateAllConfigPartial.java:1
• The generated documentation contains excessive whitespace between sentences (multiple spaces instead of single space). This appears to be a formatting issue in the source data or the generation logic. The description text should have consistent single-space separation between sentences.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The default value for quarkus.oidc.token-path ends with a trailing slash (/protocol/openid-connect/token/), which is likely incorrect. OAuth/OIDC token endpoints typically don't have trailing slashes. This should be /protocol/openid-connect/token without the trailing slash.

Suggested change

	|`/protocol/openid-connect/token/`
	|`/protocol/openid-connect/token`