Add action schema documentation

[rsenden]

Enhancement Request

With current fcli versions, documentation on fcli action yaml instructions is only provided through a JSON schema, which is useful for IDE/editor-based code assistance, but it would be good to have some proper, human-readble documentation that describes all action instructions. Furthermore, there's no documentation at all about SpEL functions that can be used in fcli actions; this should be added to the same or a separate document.

Current idea is to have this documentation generated by a build-time fcli action, somewhat similar to /fcli-action/src/main/resources/com/fortify/cli/generic_action/actions/build-time/ci-envvars.yaml. This build-time action would use SpEL functions to retrieve metadata about the action model and available SpEL functions. For example, the data returned by these functions would be processed through an for.each-record: from: ${#actionSpelFunctions} instruction.

The SpEL functions providing action & SpEL function metadata would probably live in ActionRunnerContext::ActionUtil, to allow these functions to access the SpEL context to retrieve SpEL variables/functions. Given that there's no SimpleEvaluationContext::getVariables method, we may need to have SpelHelper::registerFunctions generate a SpEL variable to contains the metadata for each registered SpEL function. Note however that in some places (like SSC/FoD action run commands), we also call SimpleEvaluationContext::setVariable to register objects that provide SpEL functions; we'll likely want to change this to call a new SpelHelper::registerObject or similar method, such that this method can generate metadata for all SpEL functions provided by that object.

To provide SpEL function metadata, we should consider adding a new SpelFunctionDescription annotation (similar to JsonPropertyDescription), or maybe a more generic SpelFunctionMetadata annotation if we want to support other metadata like preview=true, internalUseOnly=true, ... We then need to add this annotation on all methods in:

• com.fortify.cli.common.util.StringUtils
• com.fortify.cli.common.spring.expression.SpelFunctionsStandard
• com.fortify.cli.common.action.runner.ActionSpelFunctions
• com.fortify.cli.common.action.runner.ActionRunnerContext.ActionUtil
• com.fortify.cli.ssc.action.cli.cmd.SSCActionRunCommand.SSCSpelFunctions
• com.fortify.cli.fod.action.cli.cmd.FoDActionRunCommand.FoDSpelFunctions
• Maybe some others that I forgot

For action syntax, we can use a reflection-based approach similar to the existing Action::visit methods, but visiting all class members instead of only visiting non-null instructions that are used by a given action. Ideally, visiting should only be done when actually requested by the build-time documentation action, not at fcli runtime when any fcli action is executed by a user for example.

This visiting would keep track of instruction paths, to allow for fully-qualified instruction names in the output, like steps::run.fcli::cmd. For each instruction, the description is retrieved from the corresponding JsonPropertyDescription annotation and possibly other metadata annotations, like an annotation that provides an example snippet. Where possible, we should consider doing some formatting of the descriptions, like generating proper AsciiDoc lists.

The final output of the build-time documentation action would likely be an AsciiDoc document, which can then be converted to HTML/Jekyll just like we do for other documents.