annotations

Configuration Documentation Generator - annotation module

License

License

MIT
Categories

Categories

config Application Layer Libs Configuration ORM Data
GroupId

GroupId

de.sandstorm.configdocgen
ArtifactId

ArtifactId

annotations
Last Version

Last Version

0.9.3-RC2
Release Date

Release Date

Type

Type

jar
Description

Description

annotations
Configuration Documentation Generator - annotation module
Project URL

Project URL

https://github.com/sandstorm/config-doc-gen
Source Code Management

Source Code Management

https://github.com/sandstorm/config-doc-gen

Download annotations

How to add to project

<!-- https://jarcasting.com/artifacts/de.sandstorm.configdocgen/annotations/ -->
<dependency>
    <groupId>de.sandstorm.configdocgen</groupId>
    <artifactId>annotations</artifactId>
    <version>0.9.3-RC2</version>
</dependency>
// https://jarcasting.com/artifacts/de.sandstorm.configdocgen/annotations/
implementation 'de.sandstorm.configdocgen:annotations:0.9.3-RC2'
// https://jarcasting.com/artifacts/de.sandstorm.configdocgen/annotations/
implementation ("de.sandstorm.configdocgen:annotations:0.9.3-RC2")
'de.sandstorm.configdocgen:annotations:jar:0.9.3-RC2'
<dependency org="de.sandstorm.configdocgen" name="annotations" rev="0.9.3-RC2">
  <artifact name="annotations" type="jar" />
</dependency>
@Grapes(
@Grab(group='de.sandstorm.configdocgen', module='annotations', version='0.9.3-RC2')
)
libraryDependencies += "de.sandstorm.configdocgen" % "annotations" % "0.9.3-RC2"
[de.sandstorm.configdocgen/annotations "0.9.3-RC2"]

Dependencies

compile (5)

Group / Artifact Type Version
org.junit.jupiter : junit-jupiter-engine jar 5.4.0
org.jetbrains.kotlin : kotlin-stdlib-jdk8 jar 1.3.20
org.jetbrains.kotlin : kotlin-reflect jar 1.3.20
com.fasterxml.jackson.module : jackson-module-kotlin jar 2.9.8
com.fasterxml.jackson.dataformat : jackson-dataformat-yaml jar 2.9.7

Project Modules

There are no modules declared in this project.

configuration 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
de.sandstorm.configdocgen

sandstorm

sandstorm - building great web applications

Versions

Version
0.9.3-RC2
0.9.3-RC1