feat: add custom annotation for configuration property and feature fl…

…ag documentation (#2852)

* feat: add custom annotation for prop documentation

* feat: add annotation processor

* feat: annotate properties

* feat: configure annotation processor

* feat: add default value

* feat: add annotation to enum

* feat: add comment

* feat: rename annotation

* feat: rename processor class

* feat: refactor to new core module

* feat: fix test class errors

* feat: rename the module

* feat: add table and details view of content

* feat: sort properties

* feat: change wording - mandatory to required

* feat: add exception handling and logging

* feat: write file under classes output dir

* feat: create output file under target directory

* feat: rename property and file

* feat: create separate annotation for feature flags

* feat: code cleanup

* fix: add description to properties

* fix: add property descriptions from Gluu docs

* fix: add descriptions from Swagger

* fix(fido2): annotate fido config properties

* feat(scim): configure property documentation annotations

* fix: add module name to file and title

* fix: add Feature Flag descriptions

* fix: integrate doc generation with CI

* fix: add tags to generated docs

* fix: create separate sections for properties and flags

* fix: update the artifact version for jans-doc

* fix: contents of markdown files after merge

* ci: remove token req

* fix: sonar issues

* fix: sonar issues

* fix: sonar issues

* fix: move doc generation to shell script

Co-authored-by: Mohammad Abudayyeh <47318409+moabu@users.noreply.github.com>

.github/workflows/build-docs.yml

@@ -56,7 +56,10 @@ jobs:
           cp janssen-*.tgz ../
 
       - name: Generate docs
-        run: echo "Custom work on generating docs can go here."
+        run: |
+         echo "Custom work on generating docs can go here."
+         chmod u+x automation/docs/generate-property-docs.sh
+         sudo bash ./automation/docs/generate-property-docs.sh
 
       - name: git config
         run: |

.github/workflows/build-wars.yml

@@ -48,7 +48,6 @@ jobs:
     - uses: actions/checkout@v3
       with:
           repository: ${{ github.repository }}
-          token: ${{ secrets.githubtoken }}
 
     - name: find changed directories
       run: |
@@ -88,4 +87,4 @@ jobs:
           pwd
           mvn clean install -DskipTests --file ${{ matrix.fldrpath }}
           mvn -B package --file ${{ matrix.fldrpath }}/pom.xml -Dmaven.test.skip=true
-          mvn --file ${{ matrix.fldrpath }}/pom.xml deploy -Dmaven.test.skip=true
+          mvn --file ${{ matrix.fldrpath }}/pom.xml deploy -Dmaven.test.skip=true

automation/docs/generate-property-docs.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+set -euo pipefail
+
+echo "Generate properties and feature flag documents from elements annotated with @DocFeatureFlag and @DocProperty"
+
+# Compile jans-core to pick-up any changes in annotation processors
+mvn -q -f jans-core/pom.xml -DskipTests clean compile install
+
+# Compile modules where classes that use these annotations exist.
+# This will generate markdown files under target/classes directory
+mvn -q -f jans-auth-server/pom.xml clean compile
+mvn -q -f jans-fido2/pom.xml clean compile
+mvn -q -f jans-scim/pom.xml clean compile
+
+# Move markdown files to appropriate locations under documentation root 'doc'
+mv -f jans-auth-server/model/target/classes/janssenauthserver-properties.md docs/admin/reference/json/properties
+mv -f jans-auth-server/model/target/classes/janssenauthserver-feature-flags.md docs/admin/reference/json/feature-flags
+mv -f jans-fido2/model/target/classes/fido2-properties.md docs/admin/reference/json/properties
+mv -f jans-scim/model/target/classes/scim-properties.md docs/admin/reference/json/properties

docs/admin/reference/json/feature-flags/README.md

@@ -0,0 +1,6 @@
+# Overview
+
+Please use the left navigation menu to browse the content of this section while we are still working on developing content for `Overview` page.
+
+!!! Contribute
+If you’d like to contribute to this document, get started with the [Contribution Guide](https://docs.jans.io/head/CONTRIBUTING/#contributing-to-the-documentation)

docs/admin/reference/json/feature-flags/janssenauthserver-feature-flags.md

@@ -0,0 +1,214 @@
+---
+tags:
+- administration
+- reference
+- json
+- feature-flags
+---
+
+# Janssen Auth Server Feature Flags
+
+| Feature Flag Name | Description |  | 
+|-----|-----|-----|
+| ACTIVE_SESSION | Enable/Disable active session endpoint | [Details](#active_session) |
+| CIBA | Enable/Disable OpenID Connect Client Initiated Backchannel Authentication Flow(CIBA) flow support | [Details](#ciba) |
+| CLIENTINFO | Enable/Disable client info endpoint | [Details](#clientinfo) |
+| DEVICE_AUTHZ | Enable/Disable support for device authorization | [Details](#device_authz) |
+| END_SESSION | Enable/Disable end session endpoint | [Details](#end_session) |
+| HEALTH_CHECK | Enable/Disable health-check endpoint | [Details](#health_check) |
+| ID_GENERATION | Enable/Disable ID Generation endpoint | [Details](#id_generation) |
+| INTROSPECTION | Enable/Disable token introspection endpoint | [Details](#introspection) |
+| JANS_CONFIGURATION | Enable/Disable *.well-known* configuration endpoint | [Details](#jans_configuration) |
+| METRIC | Enable/Disable metric reporter feature | [Details](#metric) |
+| PAR | Enable/Disable Pushed Authorization Requests(PAR) feature | [Details](#par) |
+| REGISTRATION | Enable/Disable client registration endpoint | [Details](#registration) |
+| REVOKE_SESSION | Enable/Disable session revocation endpoint | [Details](#revoke_session) |
+| REVOKE_TOKEN | Enable/Disable token revocation endpoint | [Details](#revoke_token) |
+| SSA | Enable/Disable Software Statement Assertion(SSA) feature | [Details](#ssa) |
+| STAT | Enable/Disable Stat service | [Details](#stat) |
+| STATUS_SESSION | Enable/Disable session status check endpoint | [Details](#status_session) |
+| U2F | Enable/Disable support for Universal 2nd Factor(U2F) protocol | [Details](#u2f) |
+| UMA | Enable/Disable support for User-Managed Access (UMA) | [Details](#uma) |
+| USERINFO | Enable/Disable OpenID Connect [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) | [Details](#userinfo) |
+
+
+### ACTIVE_SESSION
+
+- Description: Enable/Disable active session endpoint
+
+- Required: No
+
+- Default value: None
+
+
+### CIBA
+
+- Description: Enable/Disable OpenID Connect Client Initiated Backchannel Authentication Flow(CIBA) flow support
+
+- Required: No
+
+- Default value: None
+
+
+### CLIENTINFO
+
+- Description: Enable/Disable client info endpoint
+
+- Required: No
+
+- Default value: None
+
+
+### DEVICE_AUTHZ
+
+- Description: Enable/Disable support for device authorization
+
+- Required: No
+
+- Default value: None
+
+
+### END_SESSION
+
+- Description: Enable/Disable end session endpoint
+
+- Required: No
+
+- Default value: None
+
+
+### HEALTH_CHECK
+
+- Description: Enable/Disable health-check endpoint
+
+- Required: No
+
+- Default value: None
+
+
+### ID_GENERATION
+
+- Description: Enable/Disable ID Generation endpoint
+
+- Required: No
+
+- Default value: None
+
+
+### INTROSPECTION
+
+- Description: Enable/Disable token introspection endpoint
+
+- Required: No
+
+- Default value: None
+
+
+### JANS_CONFIGURATION
+
+- Description: Enable/Disable *.well-known* configuration endpoint
+
+- Required: No
+
+- Default value: None
+
+
+### METRIC
+
+- Description: Enable/Disable metric reporter feature
+
+- Required: No
+
+- Default value: None
+
+
+### PAR
+
+- Description: Enable/Disable Pushed Authorization Requests(PAR) feature
+
+- Required: No
+
+- Default value: None
+
+
+### REGISTRATION
+
+- Description: Enable/Disable client registration endpoint
+
+- Required: No
+
+- Default value: None
+
+
+### REVOKE_SESSION
+
+- Description: Enable/Disable session revocation endpoint
+
+- Required: No
+
+- Default value: None
+
+
+### REVOKE_TOKEN
+
+- Description: Enable/Disable token revocation endpoint
+
+- Required: No
+
+- Default value: None
+
+
+### SSA
+
+- Description: Enable/Disable Software Statement Assertion(SSA) feature
+
+- Required: No
+
+- Default value: None
+
+
+### STAT
+
+- Description: Enable/Disable Stat service
+
+- Required: No
+
+- Default value: None
+
+
+### STATUS_SESSION
+
+- Description: Enable/Disable session status check endpoint
+
+- Required: No
+
+- Default value: None
+
+
+### U2F
+
+- Description: Enable/Disable support for Universal 2nd Factor(U2F) protocol
+
+- Required: No
+
+- Default value: None
+
+
+### UMA
+
+- Description: Enable/Disable support for User-Managed Access (UMA)
+
+- Required: No
+
+- Default value: None
+
+
+### USERINFO
+
+- Description: Enable/Disable OpenID Connect [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)
+
+- Required: No
+
+- Default value: None
+
+

docs/admin/reference/json/properties/README.md

@@ -0,0 +1,6 @@
+# Overview
+
+Please use the left navigation menu to browse the content of this section while we are still working on developing content for `Overview` page.
+
+!!! Contribute
+If you’d like to contribute to this document, get started with the [Contribution Guide](https://docs.jans.io/head/CONTRIBUTING/#contributing-to-the-documentation)

docs/admin/reference/json/properties/config-api-properties.md

@@ -0,0 +1,6 @@
+# Overview
+
+Please use the left navigation menu to browse the content of this section while we are still working on developing content for `Overview` page.
+
+!!! Contribute
+If you’d like to contribute to this document, get started with the [Contribution Guide](https://docs.jans.io/head/CONTRIBUTING/#contributing-to-the-documentation)

docs/admin/reference/json/fido.md → docs/admin/reference/json/properties/fido2-properties.md

@@ -1,9 +1,9 @@
 ---
 tags:
-  - administration
-  - reference
-  - json
-  - properties
+- administration
+- reference
+- json
+- properties
 ---
 
 # Fido2 Configuration Properties
@@ -252,5 +252,3 @@ tags:
 - Default value: None
 
 
-
-

docs/admin/reference/json/auth-server.md → docs/admin/reference/json/properties/janssenauthserver-properties.md

@@ -1,12 +1,12 @@
 ---
 tags:
-  - administration
-  - reference
-  - json
-  - properties
+- administration
+- reference
+- json
+- properties
 ---
 
-# jans-auth-server Configuration Properties
+# Janssen Auth Server Configuration Properties
 
 | Property Name | Description |  | 
 |-----|-----|-----|
@@ -2532,6 +2532,3 @@ tags:
 - Default value: None
 
 
-
-
-

docs/admin/reference/json/scim.md → docs/admin/reference/json/properties/scim-properties.md

@@ -1,9 +1,9 @@
 ---
 tags:
-  - administration
-  - reference
-  - json
-  - properties
+- administration
+- reference
+- json
+- properties
 ---
 
 # SCIM Configuration Properties
@@ -192,5 +192,3 @@ tags:
 - Default value: None
 
 
-
-

jans-auth-server/model/pom.xml

@@ -180,6 +180,11 @@
 			<groupId>com.wordnik</groupId>
 			<artifactId>swagger-annotations</artifactId>
 		</dependency>
+		<dependency>
+			<groupId>io.jans</groupId>
+			<artifactId>jans-doc</artifactId>
+			<version>${jans-core.version}</version>
+		</dependency>
 
 	</dependencies>
 </project>