feat(output-options): allow using omitzero with prefer-skip-optional-pointer

One of the key things `oapi-codegen` does is to use an "optional
pointer", following idiomatic Go practices, to indicate that a
field/type is optional.

As noted in oapi-codegen#1899, now Go 1.24+ has the `omitzero` JSON tag for
marshaling only when a type is not its zero value.

As we support generating `omitzero` JSON tags via the `x-omitzero`
extension, we can build on top of this to consider allowing the use of
`omitzero` when using the newly added global Output Option,
`prefer-skip-optional-pointer` to tune this behaviour.

This introduces a new Output Option,
`prefer-skip-optional-pointer-with-omitzero`, which mirrors behaviour
from `prefer-skip-optional-pointer`, but produces an `omitzero` flag for
any skipped pointer types, to not marshal the type if the zero value.

This allows folks using Go 1.24+ to much more ergonomically work with
different (optional) types, while allowing `omitzero` to simplify
(un)marshalling.

Right now, we don't have a straightforward means of enforcing/warning
that `oapi-codegen` is being generated into a non-Go-1.24+ project, so
we'll only document the behaviour.

Closes oapi-codegen#1899.

Author: Jamie Tanna

configuration-schema.json

@@ -243,6 +243,11 @@
           "description": "Allows defining at a global level whether to omit the pointer for a type to indicate that the field/type is optional. This is the same as adding `x-go-type-skip-optional-pointer` to each field (manually, or using an OpenAPI Overlay). A field can set `x-go-type-skip-optional-pointer: false` to still require the optional pointer.",
           "default": false
         },
+        "prefer-skip-optional-pointer-with-omitzero": {
+          "type": "boolean",
+          "description": "When using `prefer-skip-optional-pointer`, generate the `omitzero` JSON tag for types that would have had an optional pointer. This is the same as adding `x-omitzero` to each field (manually, or using an OpenAPI Overlay). A field can set `x-omitzero: false` to disable the `omitzero` JSON tag.\nNOTE that this requires Go 1.24+.\nNOTE that this must be used alongside `prefer-skip-optional-pointer`, otherwise makes no difference.",
+          "default": false
+        },
         "prefer-skip-optional-pointer-on-container-types": {
           "type": "boolean",
           "description": "Allows disabling the generation of an 'optional pointer' for an optional field that is a container type (such as a slice or a map), which ends up requiring an additional, unnecessary, `... != nil` check. A field can set `x-go-type-skip-optional-pointer: false` to still require the optional pointer.",

examples/output-options/preferskipoptionalpointerwithomitzero/Makefile

@@ -0,0 +1,36 @@
+SHELL:=/bin/bash
+
+YELLOW := \e[0;33m
+RESET := \e[0;0m
+
+GOVER := $(shell go env GOVERSION)
+GOMINOR := $(shell bash -c "cut -f2 -d. <<< $(GOVER)")
+
+define execute-if-go-124
+@{ \
+if [[ 24 -le $(GOMINOR) ]]; then \
+	$1; \
+else \
+	echo -e "$(YELLOW)Skipping task as you're running Go v1.$(GOMINOR).x which is < Go 1.24, which this module requires$(RESET)"; \
+fi \
+}
+endef
+
+lint:
+	$(call execute-if-go-124,$(GOBIN)/golangci-lint run ./...)
+
+lint-ci:
+
+	$(call execute-if-go-124,$(GOBIN)/golangci-lint run ./... --output.text.path=stdout --timeout=5m)
+
+generate:
+	$(call execute-if-go-124,go generate ./...)
+
+test:
+	$(call execute-if-go-124,go test -cover ./...)
+
+tidy:
+	$(call execute-if-go-124,go mod tidy)
+
+tidy-ci:
+	$(call execute-if-go-124,tidied -verbose)

examples/output-options/preferskipoptionalpointerwithomitzero/api.yaml

@@ -0,0 +1,44 @@
+openapi: "3.0.0"
+info:
+  version: 1.0.0
+  title: prefer-skip-optional-pointer-with-omitzero
+components:
+  schemas:
+    Client:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          description: This field is required, so will never have an optional pointer, nor `omitzero`.
+          type: string
+        id:
+          description: This field is optional, but the `prefer-skip-optional-pointer` Output Option ensures that this should not have an optional pointer. However, it will receive `omitzero`.
+          type: number
+    ClientWithExtension:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          description: This field is required, so will never have an optional pointer, nor `omitzero`.
+          type: string
+        id:
+          description: This field is optional, but the `prefer-skip-optional-pointer` Output Option ensures that this should not have an optional pointer. However, it will receive `omitzero`.
+          type: number
+        pointer_id:
+          type: number
+          description: This field should have an optional pointer, as the field-level definition of `x-go-type-skip-optional-pointer` overrides the `prefer-skip-optional-pointer` Output Option. This will also not receive an `omitzero`.
+          # NOTE that this overrides the global preference
+          x-go-type-skip-optional-pointer: false
+        no_omit:
+          type: number
+          description: This field is optional, but the `prefer-skip-optional-pointer` Output Option ensures that this should not have an optional pointer. This will not receive `omitzero`, as the field-level definition of `x-omitzero` overrides the `prefer-skip-optional-pointer-with-omitzero` Output Option.
+          # NOTE that this overrides the global preference
+          x-omitzero: false
+    NestedType:
+      type: object
+      properties:
+        client:
+          description: This field is optional, but the `prefer-skip-optional-pointer` Output Option ensures that this should not have an optional pointer.
+          $ref: '#/components/schemas/Client'

examples/output-options/preferskipoptionalpointerwithomitzero/cfg.yaml

@@ -0,0 +1,10 @@
+# yaml-language-server: $schema=../../../configuration-schema.json
+package: preferskipoptionalpointerwithomitzero
+output: gen.go
+generate:
+  models: true
+output-options:
+  # to make sure that all types are generated, even if they're unreferenced
+  skip-prune: true
+  prefer-skip-optional-pointer: true
+  prefer-skip-optional-pointer-with-omitzero: true

examples/output-options/preferskipoptionalpointerwithomitzero/gen.go

@@ -0,0 +1,91 @@
+package preferskipoptionalpointerwithomitzero
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestClient(t *testing.T) {
+	t.Run("zero value (empty string) on Name is not omitted", func(t *testing.T) {
+		client := Client{
+			Name: "",
+		}
+
+		b, err := json.Marshal(client)
+		require.NoError(t, err)
+
+		assert.True(t, jsonContainsKey(b, "name"))
+	})
+
+	t.Run("value on Name is not omitted", func(t *testing.T) {
+		client := Client{
+			Name: "some value",
+		}
+
+		b, err := json.Marshal(client)
+		require.NoError(t, err)
+
+		assert.True(t, jsonContainsKey(b, "name"))
+	})
+
+	t.Run("zero value (0.0) on Id is omitted (as `omitempty` and/or `omitzero` flags it as empty)", func(t *testing.T) {
+		client := Client{
+			Id: 0.0,
+		}
+
+		b, err := json.Marshal(client)
+		require.NoError(t, err)
+
+		assert.False(t, jsonContainsKey(b, "id"))
+	})
+
+	t.Run("value on Id is not omitted", func(t *testing.T) {
+		client := Client{
+			Id: 3.142,
+		}
+
+		b, err := json.Marshal(client)
+		require.NoError(t, err)
+
+		assert.True(t, jsonContainsKey(b, "id"))
+	})
+}
+
+func TestNestedType(t *testing.T) {
+	t.Run("zero value (empty struct) on Client is omitted", func(t *testing.T) {
+		nestedType := NestedType{
+			Client: Client{},
+		}
+
+		b, err := json.Marshal(nestedType)
+		require.NoError(t, err)
+
+		assert.False(t, jsonContainsKey(b, "client"))
+	})
+
+	t.Run("value on Client is not omitted", func(t *testing.T) {
+		nestedType := NestedType{
+			Client: Client{
+				Name: "foo",
+			},
+		}
+
+		b, err := json.Marshal(nestedType)
+		require.NoError(t, err)
+
+		assert.True(t, jsonContainsKey(b, "client"))
+	})
+}
+
+// jsonContainsKey checks if the given JSON object contains the specified key at the top level.
+func jsonContainsKey(b []byte, key string) bool {
+	var m map[string]any
+	if err := json.Unmarshal(b, &m); err != nil {
+		return false
+	}
+	_, ok := m[key]
+	return ok
+}

examples/output-options/preferskipoptionalpointerwithomitzero/gen_test.go

@@ -0,0 +1,3 @@
+package preferskipoptionalpointerwithomitzero
+
+//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen -config cfg.yaml api.yaml

examples/output-options/preferskipoptionalpointerwithomitzero/generate.go

@@ -0,0 +1,32 @@
+module github.com/oapi-codegen/oapi-codegen/v2/examples/output-options/preferskipoptionalpointerwithomitzero
+
+go 1.24
+
+replace github.com/oapi-codegen/oapi-codegen/v2 => ../../../
+
+require (
+	github.com/oapi-codegen/oapi-codegen/v2 v2.0.0-00010101000000-000000000000
+	github.com/stretchr/testify v1.10.0
+)
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/dprotaso/go-yit v0.0.0-20220510233725-9ba8df137936 // indirect
+	github.com/getkin/kin-openapi v0.128.0 // indirect
+	github.com/go-openapi/jsonpointer v0.21.0 // indirect
+	github.com/go-openapi/swag v0.23.0 // indirect
+	github.com/invopop/yaml v0.3.1 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
+	github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 // indirect
+	github.com/perimeterx/marshmallow v1.1.5 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/speakeasy-api/jsonpath v0.6.0 // indirect
+	github.com/speakeasy-api/openapi-overlay v0.10.2 // indirect
+	github.com/vmware-labs/yaml-jsonpath v0.3.2 // indirect
+	golang.org/x/mod v0.17.0 // indirect
+	golang.org/x/text v0.20.0 // indirect
+	golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)