OpenAPITools / OpenAPITools/openapi-generator
[REQ] Embed the version of the generator tooling itself into the output generated source
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 26.8k
- Forks
- 7.7k
- PR merge metrics
- PR metrics pending
Description
Is your feature request related to a problem? Please describe.
A problem arose this week where it was discovered that there's an incompatibility between two build systems we utilize at work which resulted in generated code that was divergent from each other and the cause was unknown and chasing after the versioning of the tooling was very murky.
Describe the solution you'd like
For the version a given openapi generator was cut from include the git sha and perhaps a formal git tag or official version of the tooling or something of that nature and output that information directly into the file header comments of the generated output source identifying the source of the generator tooling itself, something like
/*--------------
This file was generated using openapi-genetator
version: 1.2.3
sha: 0fffffffffff
-----------------*/
Perhaps doing this for at least one file, such as the top level __init__.py file or a main class or something central like that if doing it for every file is considered excessive.
Describe alternatives you've considered
I tried to look at other differences in the generated source including the string The version of the OpenAPI document: <versionX> and the __version__ attribute but both were misleading in the end for determining at first glance which build tooling was ahead of the other with respect to the git repo of the generator tooling.
There was also a user_agent member data string that look promising but didn't give a clear picture either
Additional context
To accelerate debugging API differences between build tooling make the version of the generator embedded in the output source that gets generated.
For instance diffing two files of the same api spec generated under two build systems yielded the following
bazel
The version of the OpenAPI document: 1.49.2
that came from a version of openapi-generator at this version
https://github.com/OpenAPITools/openapi-generator/tree/2250aae6a6488278f001332fe4a2ef97dfc209bf
pypi
The version of the OpenAPI document: 1.50.3
that came from a version of openapi-generator at this version
https://github.com/OpenAPITools/openapi-generator/tree/v6.6.0
There was a bit more complexity involved since the docker hub cli tool was in the mix and the relationship of those docker tools to the actual github repo itself is muddy as well for me since in github the project is
https://github.com/OpenAPITools/openapi-generator
but in docker hub the project is identified as openapi-generator-cli
https://hub.docker.com/layers/openapitools/openapi-generator-cli/v6.6.0/images/sha256-54381220aecf2e77bb4b6694c4e1a03e733b49453292cd1af6f48b510f1f008a
Having the generators relate back to the parent github repo that everything stems from will be beneficial to cut to the chase regarding what tooling originated from what version of the generator source.
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 by locating where generated file headers are assembled and inspect the central output mentioned in the issue, such as a top-level init.py or main class. Trace how the generator’s version metadata is available to that path. Done means generated source identifies the generator version and git SHA clearly enough to distinguish tooling builds.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100