[suggestion] Gradle plugin input file instead of input string

[stefankoppier]

Suggestion: deprecate inputSpec and replace it with inputFile. The difference is that inputFile is of type File instead of String. File plays more nicely with Gradle built-ins, like rootDir and layout.

This reduces the need for some complexity in some cases, e.g. layout.buildDirectory.file("spec.yaml").map { it.asFile.absolutePath } to layout.buildDirectory.file("spec.yaml") while staying relatively simple for existing String paths x by wrapping the string in the built-in file(x).

Currently just a draft PR, as it is not complete: tests and documentation is missing. Merely for discussion purpose atm.

Resolves #17380, although I personally wouldn't consider it a bug.

PR checklist

• Read the contribution guidelines.
• Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
• Run the following to build the project and update samples:

  ./mvnw clean package 
  ./bin/generate-samples.sh ./bin/configs/*.yaml
  ./bin/utils/export_docs_generators.sh
  

  (For Windows users, please run the script in Git BASH)
  Commit all changed files.
  This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
  These must match the expectations made by your contribution.
  You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
  IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
• File the PR against the correct branch: master (upcoming 7.1.0 minor release - breaking changes with fallbacks), 8.0.x (breaking changes without fallbacks)
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

[stefankoppier]

@wing328 when you have the time, could you give this a look and give your opinion?

[wing328]

the input can be a URL, right?

[wing328]

also maven plugin uses the same name and we want to make it consistent across plugins (maven, sbt, etc) if possible

[stefankoppier]

the input can be a URL, right?

It could, but it has similar issues as string. You would need to map the Gradle methods to a URL, instead of a String. Why do you ask? :)

[stefankoppier]

also maven plugin uses the same name and we want to make it consistent across plugins (maven, sbt, etc) if possible

I agree. If you support the general idea of the PR, I will include that in the final PR.

[wing328]

deprecate inputSpec and replace it with inputFile.

because the new name inputFile kinda suggests it only works with file only

instead of deprecating inputSpec, what about adding another option "inputFile" instead?

if later most people prefer inputFile, we can then mark inputSpec as deprecated.