feat: add custom annotation for configuration property and feature flag documentation

[ossdhaval]

Prepare

• Read PR guidelines
• Read license information

---

Description

PR is work in progress and aimed to gather feedback on approach towards automating documentation of configuration properties and feature flags

The problem that we are trying to solve is of missing out on documenting properties and feature flags. Developers often add these elements without updating relevant documentation resulting in the user not being aware of the feature or property setting.

If developers can have a simple annotation to take care of generating the documentation, it will make sure that code and documentation will stay in synch for properties and feature flags.

The proposed approach leverages annotation processing at compile time. It involves

• A custom annotation
• A custom annotation processor
• Applying custom annotation to properties and feature flag fields

A sample of generated markdown looks like below:

Tasks:

• Create custom annotation
• Create annotation processor
• Figure out how to process annotation at compile time
• Generate markdown doc from annotation
• Integrate with the build system so the markdown doc is generated and committed to jans\docs

Review comments:

• Make properties in the doc as anchor tags so that they can be directly referred to via link (Mike)
• Properties should be listed in alphabetical order (Mike)
• Create a new maven module (Yuriz)
• Review the annotation name (Yuriz)

Target issue

closes #issue-number-here

Implementation Details

---

Test and Document the changes

• Static code analysis has been run locally and issues have been fixed
• Relevant unit and integration tests have been added/updated
• Relevant documentation has been updated if any (i.e. user guides, installation and configuration guides, technical design docs etc)

[ossdhaval]

Adding feedback from @nynymike here

[yuriyz]

At first I was going to ask why don't use markdown template and substituting, like in https://github.com/kongchen/swagger-maven-plugin (sample generated doc https://raw.githubusercontent.com/kongchen/swagger-maven-example/master/generated/document.html).

But here it seems goal is to generate separate markdown files for each java file and then inject into docs, right?
Own generator gives flexibility like it's done in this PR. Lets introduce separate jans-doc maven module for doc purpose. Also lets take better name. @JansConfigProperty sounds confusing, like some AS configuration (or jans-config-api related configuration). Maybe something like @DocProperty ?

[moabu]

I think this is good approach but im a bit confused here. I think @yuriyz brings up a good note. We are already adding work to our swagger annotations and the more we can add there the less we have to spread out. Meaning less is more for documentation purposes its easier to serve it from one place. With the automation purpose in mind my question would be if we actually miss anything if we follow one spec instead of doing this? Too many is confusing from the users point of view and the developers too. If there is a huge union between swagger spec that can be generated vs this we should reconsider and continue the efforts with our swagger documentation as is being done with config-api.

#2353

[ossdhaval]

@moabu @yuriyz

The purpose here is to make sure documentation about these properties and flags is easily accessible as well as providing developers with a way to do that.

Having these properties documented in our doc site (markdown) has a few advantages:

• We can control the format of the document. It would be very clear and will have only the things that we need.
• We can have anchor links to property descriptions. This will allow us to refer to them from other docs.
• Searchable. If I search for the property/flag name in the documentation site, I'll find it if it is there as markdown file. In case of swagger documentation, we will have to link it to the doc site and that will make property/flag names unsearchable.

About using Swagger spec:

• I'll need more pointers on this as I have seen swagger being used to document only REST API. While what we have here are private fields from Java classes and Enumerations
• Also, even though we can do this via Swagger spec, I doubt if we will have a clean UI or the ability to point to a particular property description.

About the current approach:

• Yes, it is custom, but it is very lightweight. So, it is easy to maintain
• It is custom, so we have more control.
• Can generate markdown which can be directly injected into the doc site source.

[moabu]

We can switch swagger to markdown but with that said if we are planning to move ahead with the above proposal lets agree on the following:

1. We use swagger for documenting all our apies always. Hence, we don't converge or duplicate items but rather we annotate all the APIs extensivley using swagger annotations.
2. Anything besides APIs can be documented in the above method. Moreover, as @yuriyz mentioned in his comment the module jans-doc should be introduced and we shouldn't use any overlapping names such as @JansConfigProperty as that's very confusing.

[ossdhaval]

I agree. Summarizing documentation approaches.

• REST API -> Swagger
• Java API -> javadoc
• Java API that needs to be part of the Documentation site -> Custom annotation

Raised #2938 to add these as guideline to developer documentation.

I'll create jans-doc module.

[ossdhaval]

Let me know if @DocumentedJansProperty is a better name than @JansConfigProperty.

[yuriyz]

Just @DocProperty sounds good to me. It will be located in io.jans.docs package, so it's clear it's jans.

[yuriyz]

@ossdhaval is it possible to generate swagger spec without REST API stuff. I mean just models? There are different tools that can generate markdown out of swagger. In this case we can continue to use swagger annotation and use markdown in our docs from models. I guess this is what @moabu meant.

cc @pujavs , she may know the answer for generator.

[moabu]

@ossdhaval is it possible to generate swagger spec without REST API stuff. I mean just models? There are different tools that can generate markdown out of swagger. In this case we can continue to use swagger annotation and use markdown in our docs from models. I guess this is what @moabu meant.

cc @pujavs , she may know the answer for generator.

Yes that's exactly what I meant . We can cover a lot with swagger and easily convert to markdown. There shouldn't be an overlap .

[sonarcloud]

[jans-config-api-parent] Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

[sonarcloud]

[notify] Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

[sonarcloud]

[jans-linux-setup] Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

[ossdhaval]

@yuriyz @shmorri @moabu PR is ready for review with all checks passing and conflicts resolved.

[moabu]

please inject a bash script at https://github.com/JanssenProject/jans/tree/main/automation under a new folder docs. This will allow the workflows to be a little bit cleaner as I suspect we will have more of these flows.

[ossdhaval]

@moabu Done. I have moved these commands to a separate script. Please check.

[yuriyz]

@ossdhaval lets fix bugs found by sonar

[jans-core] SonarCloud Quality Gate failed.   

2 Bugs
0 Vulnerabilities
2 Security Hotspots
11 Code Smells

0.0% Coverage
8.6% Duplication

[sonarcloud]

[jans-core] SonarCloud Quality Gate failed.   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
2 Code Smells

0.0% Coverage
28.4% Duplication

[ossdhaval]

@ossdhaval lets fix bugs found by sonar

[jans-core] SonarCloud Quality Gate failed.   

2 Bugs 0 Vulnerabilities 2 Security Hotspots 11 Code Smells

0.0% Coverage 8.6% Duplication

@yuriyz Thanks for highlighting this. I have now taken care of most of these Sonar issues. There are two due to duplicate code. The check is failing due to the same reason. Some amount of this duplicate code is intentional to allow customized formating of the document if needed. One method createAndWriteDoc can still be extracted out to an abstract class. I tried but ran into problems where the compiler couldn't instantiate the child class as an annotation processor. Hence I have left that method as is.