JarCastingconfiguration documentation generator
This tool enables you to generate a Configuration Documentation (similar to a JavaDoc) from your source code. For now, there is support for Spring Boot and Standalone.
Main Features
- documentation parsing from java doc comments
- explicit or automatic recognition of configuration code
- code documentation validator (configurable compiler warning or error, e.g. fail build on missing doc comment)
- interactive React UI for configuration documentation browsing
- other configurable output format (JSON, NONE)
- easily usable with build tools (e.g. gradle)
- supports Lombok
The releases are available on the maven central repository.
repositories {
mavenCentral()
}
Snapshot releases or local maven repositories:
repositories {
maven { url "https://oss.sonatype.org/content/repositories/snapshots" }
// mavenLocal()
}
Basic Settings
The annotation processor is configured via YAML file. The path (URL) can be specified via argument de.sandstorm.configdocgen.settingsFile.
Example: -Ade.sandstorm.configdocgen.settingsFile=file:///home/user/config-doc.yml
Example using a config in src/main/resources via gradle:
compileJava {
options.compilerArgs += ["-Ade.sandstorm.configdocgen.settingsFile=file://" + sourceSets.main.resources.sourceDirectories.asPath + "/config-doc.yaml"]
}
Settings:
# The application name
# default: "No module name set!"
moduleName: 'Your application name'
# Processor settings
processor:
# Compiler behavior for missing documentation comments
# All javax.tools.Diagnostic.Kind enum constants are allowed:
# - ERROR
# - WARNING
# - MANDATORY_WARNING
# - NOTE
# - OTHER
# default: WARNING
missingDocCommentDiagnostic: WARNING
writer:
# The output writer type
# All de.sandstorm.configdocgen.core.WriterType enum constants are allowed:
# - JSON
# - REACT_UI
# - NONE
type: REACT_UI
# The output file name
# default depends on the writer type:
# - JSON = "config-doc.json"
# - REACT_UI = "config-doc-react-ui.html"
# - NONE = no output
outputFileName: 'config-doc.html'
It may be a good idea to set the processor.missingDocCommentDiagnostic to ERROR. This enforces the developers to comment the applications public API.
Module Version
ConfigDocGen can compile your application / module version into its output. Set the value via argument de.sandstorm.configdocgen.moduleVersion. Example: -Ade.sandstorm.configdocgen.moduleVersion=org.app.module--master-#commitID
Example of writing the project name / version and git info with gradle:
compileJava {
options.compilerArgs += ["-Ade.sandstorm.configdocgen.moduleVersion=${getModuleVersionForConfigDoc()}"]
}
def getModuleVersionForConfigDoc() {
return project.name + "-" +
project.version + "-" +
"git rev-parse --abbrev-ref HEAD".execute().text.replaceAll("\n", "") + "-" +
"#" + "git rev-parse --short HEAD".execute().text
}
Standalone
Generate configuration documentation using custom annotations in your code.
TODO: documentation of custom annotations!!!
Spring Boot
Generate configuration documentation from Spring Boot sources.
All @ConfigurationProperties classes are scanned as namespaces with fields as configuration properties.
Usage with Spring Boot
add the following annotation processor dependency to the projects build.gradle:
ext.configDocVersion = "0.9.0-RC1"
dependencies {
annotationProcessor "de.sandstorm.configdocgen:processor-spring:${configDocVersion}"
}
You may update the configDocVersion or set it via gradle properties.
local dev
Requirements:
- git
- a running Docker deamon
- JDK 11
Run tests:
./gradlew clean test
React UI (using docker):
enter the utility directory:
cd local-dev/react-ui/
Setup local development environment:
./setup.sh
Run UI dev server in watch mode:
./start.sh
Package the React UI resources to the core module.
./package-ui.sh
Enter bash (e.g. for yarn add some-new-package)
./bash.sh
