Allow overriding the binary version when VCS not available (#1163)

As mentioned in #1046, for environments, like Nix, that build without a
Version Control System (VCS) available, we output `(devel)` as the
version of oapi-codegen even when it's building from source from a Git
tag.

We can therefore provide a `noVCSVersionOverride` build-time flag to
allow us to override this with an arbitrary string.

Closes #1046.

Co-authored-by: Jamie Tanna <[email protected]>

cmd/oapi-codegen/oapi-codegen.go

@@ -78,6 +78,10 @@ type oldConfiguration struct {
  Compatibility codegen.CompatibilityOptions `yaml:"compatibility"`
 }
 
+// noVCSVersionOverride allows overriding the version of the application for cases where no Version Control System (VCS) is available when building, for instance when using a Nix derivation.
+// See documentation for how to use it in examples/no-vcs-version-override/README.md
+var noVCSVersionOverride string
+
 func main() {
  flag.StringVar(&flagOutputFile, "o", "", "Where to output generated code, stdout is default.")
  flag.BoolVar(&flagOldConfigStyle, "old-config-style", false, "Whether to use the older style config file format.")
@@ -115,7 +119,11 @@ func main() {
  os.Exit(1)
  }
  fmt.Println(bi.Main.Path + "/cmd/oapi-codegen")
- fmt.Println(bi.Main.Version)
+ version := bi.Main.Version
+ if len(noVCSVersionOverride) > 0 {
+ version = noVCSVersionOverride
+ }
+ fmt.Println(version)
  return
  }
 
@@ -263,6 +271,10 @@ func main() {
  errExit("error loading swagger spec in %s\n: %s", flag.Arg(0), err)
  }
 
+ if len(noVCSVersionOverride) > 0 {
+ opts.Configuration.NoVCSVersionOverride = &noVCSVersionOverride
+ }
+
  code, err := codegen.Generate(swagger, opts.Configuration)
  if err != nil {
  errExit("error generating code: %s\n", err)

examples/no-vcs-version-override/README.md

@@ -0,0 +1,17 @@
+# Overriding the version of oapi-codegen
+
+## Why?
+
+oapi-codegen uses the standard Go means to determine what the version of the binary is.
+
+However, this doesn't work when there's no Version Control System (VCS), for instance when building from a source bundle.
+
+This example shows how to override the version at build-time.
+
+## How?
+
+By specifying `-ldflags` for the `noVCSVersionOverride` when running `go build` or `go run`:
+
+```sh
+go run -ldflags "-X main.noVCSVersionOverride=v123.456.789" ./cmd/oapi-codegen --config=config.yaml ../../api.yaml
+```

examples/no-vcs-version-override/api.yaml

@@ -0,0 +1,14 @@
+openapi: "3.0.0"
+info:
+ version: 1.0.0
+ title: NOOP API
+ description: An test API to check some build-time features
+paths:
+ /nothing:
+ get:
+ operationId: getNothing
+ description: |
+ Returns nothing as expected
+ responses:
+ 200:
+ description: Ok

examples/no-vcs-version-override/echo/api/config.yaml

@@ -0,0 +1,6 @@
+package: api
+generate:
+ echo-server: true
+output: api.gen.go
+output-options:
+ skip-prune: true

examples/no-vcs-version-override/echo/api/doc.go

@@ -0,0 +1,3 @@
+package api
+
+//go:generate go run -ldflags "-X main.noVCSVersionOverride=v123.456.789" github.com/deepmap/oapi-codegen/cmd/oapi-codegen --config=config.yaml ../../api.yaml

pkg/codegen/codegen.go

@@ -272,7 +272,12 @@ func Generate(spec *openapi3.T, opts Configuration) (string, error) {
  w := bufio.NewWriter(&buf)
 
  externalImports := append(globalState.importMapping.GoImports(), importMap(xGoTypeImports).GoImports()...)
- importsOut, err := GenerateImports(t, externalImports, opts.PackageName)
+ importsOut, err := GenerateImports(
+ t,
+ externalImports,
+ opts.PackageName,
+ opts.NoVCSVersionOverride,
+ )
  if err != nil {
  return "", fmt.Errorf("error generating imports: %w", err)
  }
@@ -768,7 +773,7 @@ func GenerateEnums(t *template.Template, types []TypeDefinition) (string, error)
 }
 
 // GenerateImports generates our import statements and package definition.
-func GenerateImports(t *template.Template, externalImports []string, packageName string) (string, error) {
+func GenerateImports(t *template.Template, externalImports []string, packageName string, versionOverride *string) (string, error) {
  // Read build version for incorporating into generated files
  // Unit tests have ok=false, so we'll just use "unknown" for the
  // version if we can't read this.
@@ -782,6 +787,9 @@ func GenerateImports(t *template.Template, externalImports []string, packageName
  if bi.Main.Version != "" {
  moduleVersion = bi.Main.Version
  }
+ if versionOverride != nil {
+ moduleVersion = *versionOverride
+ }
  }
 
  context := struct {

pkg/codegen/configuration.go

@@ -18,6 +18,9 @@ type Configuration struct {
  OutputOptions OutputOptions `yaml:"output-options,omitempty"`
  ImportMapping map[string]string `yaml:"import-mapping,omitempty"` // ImportMapping specifies the golang package path for each external reference
  AdditionalImports []AdditionalImport `yaml:"additional-imports,omitempty"`
+ // NoVCSVersionOverride allows overriding the version of the application for cases where no Version Control System (VCS) is available when building, for instance when using a Nix derivation.
+ // See documentation for how to use it in examples/no-vcs-version-override/README.md
+ NoVCSVersionOverride *string `yaml:"-"`
 }
 
 // GenerateOptions specifies which supported output formats to generate.