OpenAPITools / OpenAPITools/openapi-generator

[REQ] [Docs] Gradle Plugin: Remove explicit .toString() in inputSpec & outputDir, or explicitly document its need

Open
#6,866 1 comment 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Enhancement: Feature
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.