OpenAPITools / OpenAPITools/openapi-generator-cli

[Feature request, Documentation] self-contained (npx) script with a selection of generator version as a CLI parameter

オープン
#417 コメント 1 件 リアクション 5 件 担当者 1 名 GitHub で見る

@kay-schecker がすでに取り組んでいます。

2021年7月13日 から。

bug
主要言語
TypeScript
スター
2k
フォーク
208
平均マージ
7時間 12分
マージ済み PR(30日)
6

説明

Current documentation only describes how to install the generator CLI globally (which is very impractical for any collaborative projects, especially when it comes to updating) or as a part of the project (note: you also forgot to add -D in a Locally (recommended) step).

There is also a new openapitools.json file introduced without describing any steps how we can avoid using it, especially if we intend to just accept its defaults anyway. When it comes to selecting the version of generator, documentation only provides a separate openapi-generator-cli version-manager set 4.0.0 command, but there doesn't seem to be an option to generate directly with a specified version without configuring it globally.

  • Does this mean we have to 1. backup any old openapitools.json, 2. set the version, 3. run the generator, 4. delete the openapitools.json, and (optionally) 5. restore any old openapitools.json if we want to make this process self-contained?
  • For example, https://github.com/OpenAPITools/openapi-generator-cli/issues/386 describes a common default lazy setup that most developers will use without worrying about consequences, where we don't define any version, so the latest one is used automatically, and the openapitools.json gets created for no reason during the CI process.

Motivation: The main use-case (other than being unwilling to bloat the project) would be having multiple schemas in a larger project where we want to update the version of each script individually instead of controlling them all using the same openapitools.json file. (Sometimes we can't afford to impact someone else's code by our upgrade, as we need to quickly add a schema while keeping the project maintainable by keeping scripts compatible with CI instead of just copying the generated code, making us waste hours as we come up with workarounds.) We may also want to avoid installing this CLI to the project altogether, which is what npx is generally used for; especially if we want to run an encapsulated npm script from an environment that doesn't perform a full npm i. Also it makes it easier to always use latest CLI, only specifying version of the generator. There are many perspectives where "just running the generator" is the most preferable step, which is now difficult to do if we don't always want to use the latest version (including scenario when a private npm repo used by CI hasn't approved and mirrored new update yet).

Context: I had been using npx @openapitools/openapi-generator-cli@cli-4.3.1 generate as part of custom npm scripts. However, in the latest versions I'm unable to use npx @openapitools/openapi-generator-cli@cli-5.2.0 generate anymore.

Suggested solution: Add the following switches to generate command:

  • --standalone - skip using or generating openapitools.json for this run (also fixes #386 if properly documented in context of CI). Use default; but maybe an option to override individual parameters via CLI could also replace the need for a second switch, e.g. as --standalone={"generator-cli":{"version":"5.2.0"}}
  • --use-generator-cli-version - override generator-cli.version configuration for this run only

コントリビューションガイド

このリポジトリのコントリビューションガイドは索引されていません

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

評価

この issue はまだ評価されていません。

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。