[doc] Document usage of post-process file feature (#7315)

Author: jimschubert

docs/file-post-processing.md

@@ -0,0 +1,70 @@
+---
+id: file-post-processing
+title: File post-processing
+---
+
+Each tool (CLI and plugins) supports enabling file post-processing at a high-level. Enabling this option allows for generators which support post-processing to call some external process for each generated file, passing the file path to that tool. The external tool must be defined in an environment variable supported by the generator.
+
+Note that:
+
+* this option is `--enable-post-process-file` in the CLI and `enablePostProcessFile` in plugins
+* we require _both_ specifying the environment variable _and_ enabling the option at the tooling level; this feature is opt-in for security 
+* file processing occurs one at a time
+* the external tool may be a custom script which invokes multiple tools
+
+Also refer to the relevant documentation for [CLI](./usage.md), [Maven Plugin](https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-maven-plugin/README.md), [Gradle Plugin](https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-gradle-plugin/README.adoc), or [SBT Plugin](https://github.com/OpenAPITools/sbt-openapi-generator/blob/master/README.md).
+
+## Supported Environment Variables
+
+The following environment variables are supported by their respective generators:
+<!-- query with: grep -Rn '_POST_PROCESS_FILE"' modules | grep -Eo '[^"]+_POST_PROCESS_FILE' | sort -u -->
+
+* `CPP_POST_PROCESS_FILE`
+* `CSHARP_POST_PROCESS_FILE`
+* `C_POST_PROCESS_FILE`
+* `DART_POST_PROCESS_FILE`
+* `FSHARP_POST_PROCESS_FILE`
+* `GO_POST_PROCESS_FILE`
+* `HASKELL_POST_PROCESS_FILE`
+* `JAVA_POST_PROCESS_FILE`
+* `JS_POST_PROCESS_FILE`
+* `KOTLIN_POST_PROCESS_FILE`
+* `OCAML_POST_PROCESS_FILE`
+* `PERL_POST_PROCESS_FILE`
+* `PHP_POST_PROCESS_FILE`
+* `POWERSHELL_POST_PROCESS_FILE`
+* `PYTHON_POST_PROCESS_FILE`
+* `RUBY_POST_PROCESS_FILE`
+* `RUST_POST_PROCESS_FILE`
+* `SCALA_POST_PROCESS_FILE`
+* `SWIFT_POST_PROCESS_FILE`
+* `TS_POST_PROCESS_FILE`
+
+## Example
+
+Let's see how to pass Ruby generated files to Rubocop, a static code analysis/linter/formatter tool.
+
+```
+# First, export the required environment variable
+export RUBY_POST_PROCESS_FILE="/usr/local/bin/rubocop -a"
+
+export OPENAPI_DOC="https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"
+
+# Invoke the generator with --enable-post-process-file
+openapi-generator generate --enable-post-process-file -i $OPENAPI_DOC -g ruby -o .out-ruby/
+```
+
+You will now see messages logged about which files have been processed:
+
+```
+[main] INFO  o.o.codegen.TemplateManager - writing file /Users/jim/projects/openapi-generator/.out-ruby/.rspec
+[main] INFO  o.o.codegen.TemplateManager - writing file /Users/jim/projects/openapi-generator/.out-ruby/spec/spec_helper.rb
+[main] INFO  o.o.c.languages.AbstractRubyCodegen - Successfully executed: /usr/local/bin/rubocopy -a /Users/jim/projects/openapi-generator/.out-ruby/spec/spec_helper.rb
+[main] INFO  o.o.codegen.TemplateManager - writing file /Users/jim/projects/openapi-generator/.out-ruby/spec/configuration_spec.rb
+[main] INFO  o.o.c.languages.AbstractRubyCodegen - Successfully executed: /usr/local/bin/rubocopy -a /Users/jim/projects/openapi-generator/.out-ruby/spec/configuration_spec.rb
+[main] INFO  o.o.codegen.TemplateManager - writing file /Users/jim/projects/openapi-generator/.out-ruby/spec/api_client_spec.rb
+[main] INFO  o.o.c.languages.AbstractRubyCodegen - Successfully executed: /usr/local/bin/rubocopy -a /Users/jim/projects/openapi-generator/.out-ruby/spec/api_client_spec.rb
+[main] INFO  o.o.codegen.TemplateManager - Skipped /Users/jim/projects/openapi-generator/.out-ruby/.openapi-generator-ignore (Skipped by supportingFiles options supplied by user.)
+[main] INFO  o.o.codegen.TemplateManager - writing file /Users/jim/projects/openapi-generator/.out-ruby/.openapi-generator/VERSION
+[main] INFO  o.o.codegen.TemplateManager - writing file /Users/jim/projects/openapi-generator/.out-ruby/.openapi-generator/FILES
+```

docs/usage.md

@@ -522,6 +522,12 @@ openapi-generator generate \
 
 > NOTE: mappings are applied to `DateTime`, as this is the representation of the primitive type. See [DefaultCodegen](https://github.com/OpenAPITools/openapi-generator/blob/7cee999543fcc00b7c1eb9f70f0456b707c7f9e2/modules/openapi-generator/src/main/java/org/openapitools/codegen/DefaultCodegen.java#L1431).
 
+#### File Post-Processing
+
+The `--enable-post-process-file` option enables specific generators to invoke some external language-specific formatting script. Each filename is passed _individually_ to this external script, allowing for linting, formatting, or other custom clean-up.
+
+For more details, see [File Post-Processing](./file-post-processing.md).
+
 ### Target External Models
 
 Sometimes you don't want the codegen to make a model for you--you might want to just include one that already exists in your codebase.  Say you already have a `User` object and want to reuse that, which has a different model package from the other generated files:

modules/openapi-generator-cli/src/main/java/org/openapitools/codegen/cmd/Generate.java

@@ -234,7 +234,7 @@ public class Generate extends OpenApiGeneratorCommand {
                     + " Useful for piping the JSON output of debug options (e.g. `--global-property debugOperations`) to an external parser directly while testing a generator.")
     private Boolean logToStderr;
 
-    @Option(name = {"--enable-post-process-file"}, title = "enable post-process file", description = CodegenConstants.ENABLE_POST_PROCESS_FILE_DESC)
+    @Option(name = {"--enable-post-process-file"}, title = "enable post-processing of files (in generators supporting it)", description = CodegenConstants.ENABLE_POST_PROCESS_FILE_DESC)
     private Boolean enablePostProcessFile;
 
     @Option(name = {"--generate-alias-as-model"}, title = "generate alias (array, map) as model", description = CodegenConstants.GENERATE_ALIAS_AS_MODEL_DESC)

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/OCamlClientCodegen.java

@@ -437,7 +437,7 @@ public void processOpts() {
 
         if (StringUtils.isEmpty(System.getenv("OCAML_POST_PROCESS_FILE"))) {
             LOGGER.info("Hint: Environment variable 'OCAML_POST_PROCESS_FILE' (optional) not defined. E.g. to format the source code, please try 'export OCAML_POST_PROCESS_FILE=\"ocamlformat -i --enable-outside-detected-project\"' (Linux/Mac)");
-            LOGGER.info("Note: To enable file post-processing, 'enablePostProcessFile' must be set to `true` (--enable-post-process-file for CLI).");
+            LOGGER.info("NOTE: To enable file post-processing, 'enablePostProcessFile' must be set to `true` (--enable-post-process-file for CLI).");
         } else if (!this.isEnablePostProcessFile()) {
             LOGGER.info("Warning: Environment variable 'OCAML_POST_PROCESS_FILE' is set but file post-processing is not enabled. To enable file post-processing, 'enablePostProcessFile' must be set to `true` (--enable-post-process-file for CLI).");
         }

website/sidebars.js

@@ -6,7 +6,8 @@ module.exports = {
       'plugins',
       'online',
       'usage',
-      'globals'
+      'globals',
+      'file-post-processing'
     ],
     'Extending': [
       'templating',