OpenAPITools / OpenAPITools/openapi-generator

[REQ] Embed the version of the generator tooling itself into the output generated source

Open
#22,264 4 comments 0 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

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.

Image

There was also a user_agent member data string that look promising but didn't give a clear picture either

Image

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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.