OpenAPITools / OpenAPITools/openapi-generator
[REQ] [Docs] Gradle Plugin: Remove explicit .toString() in inputSpec & outputDir, or explicitly document its need
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 26.8k
- Forks
- 7.7k
- PR merge metrics
- PR metrics pending
Description
Within the definition of Gradle tasks (for example openApiGenerate) inside a README of OpenAPI Generator Gradle Plugin there are two parameters with String as their type, specifically inputSpec and outputDir. They are being assigned a GString explicitly converted to String using .toString(), which (arguably) creates a noise in the Gradle configuration files of any projects who follow this example, even though an implicit conversion is also possible (just like in Java). Groovy documentation says that it will typically auto-cast between GString and String if an API declares the type of a parameter, which it does.
Because the reasoning behind this approach isn't documented anywhere, and there's no issue addressing this yet, I'd like to recommend reconsidering the default. If there's any reason why this should be preferred, please document it to reduce a risk of someone introducing the bug during a project cleanup. As far as I know, the only downside would be that the API could hypothetically also add a support for an Object type in the future, causing a wrong default cast (which the framework should safely cover anyway).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with modules/openapi-generator-gradle-plugin/README.adoc and the openApiGenerate example, focusing on the inputSpec and outputDir parameters. Check whether the documented Gradle Plugin usage requires explicit .toString() conversion; done means the example and its rationale are either updated consistently or the need for conversion is clearly documented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- groovy
- Domain
- build-system, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100