docs: add example of using go tool for Go 1.24+

Jamie Tanna · jamietanna · commit 2647a108f5fd · 2025-02-20T15:48:42.000Z
diff --git a/README.md b/README.md
@@ -42,6 +42,25 @@ go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest
 
 ## Install
 
+## For Go 1.24+
+
+It is recommended to follow [the `go tool` support available from Go 1.24+](https://www.jvt.me/posts/2025/01/27/go-tools-124/) for managing the dependency of `oapi-codegen` alongside your core application.
+
+To do this, you run `go get -tool`:
+
+```sh
+$ go get -tool github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest
+# this will then modify your `go.mod`
+```
+
+From there, each invocation of `oapi-codegen` would be used like so:
+
+```go
+//go:generate go tool github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen -config cfg.yaml ../../api.yaml
+```
+
+## Prior to Go 1.24
+
 It is recommended to follow [the `tools.go` pattern](https://www.jvt.me/posts/2022/06/15/go-tools-dependency-management/) for managing the dependency of `oapi-codegen` alongside your core application.
 
 This would give you a `tools/tools.go`:
diff --git a/examples/minimal-server/stdhttp-go-tool/Makefile b/examples/minimal-server/stdhttp-go-tool/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 ./... --out-format=colored-line-number --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)
diff --git a/examples/minimal-server/stdhttp-go-tool/api/cfg.yaml b/examples/minimal-server/stdhttp-go-tool/api/cfg.yaml
@@ -0,0 +1,6 @@
+# yaml-language-server: $schema=../../../../configuration-schema.json
+package: api
+output: ping.gen.go
+generate:
+  models: true
+  std-http-server: true
diff --git a/examples/minimal-server/stdhttp-go-tool/api/generate.go b/examples/minimal-server/stdhttp-go-tool/api/generate.go
@@ -0,0 +1,3 @@
+package api
+
+//go:generate go tool github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen -config cfg.yaml ../../api.yaml
diff --git a/examples/minimal-server/stdhttp-go-tool/api/impl.go b/examples/minimal-server/stdhttp-go-tool/api/impl.go
@@ -0,0 +1,25 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+)
+
+// ensure that we've conformed to the `ServerInterface` with a compile-time check
+var _ ServerInterface = (*Server)(nil)
+
+type Server struct{}
+
+func NewServer() Server {
+	return Server{}
+}
+
+// (GET /ping)
+func (Server) GetPing(w http.ResponseWriter, r *http.Request) {
+	resp := Pong{
+		Ping: "pong",
+	}
+
+	w.WriteHeader(http.StatusOK)
+	_ = json.NewEncoder(w).Encode(resp)
+}
diff --git a/examples/minimal-server/stdhttp-go-tool/api/ping.gen.go b/examples/minimal-server/stdhttp-go-tool/api/ping.gen.go
diff --git a/examples/minimal-server/stdhttp-go-tool/go.mod b/examples/minimal-server/stdhttp-go-tool/go.mod
@@ -0,0 +1,27 @@
+module github.com/oapi-codegen/oapi-codegen/v2/examples/minimal-server/stdhttp-go-tool
+
+go 1.22
+
+replace github.com/oapi-codegen/oapi-codegen/v2 => ../../../
+
+tool github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen
+
+require (
+	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/oapi-codegen/oapi-codegen/v2 v2.0.0-00010101000000-000000000000 // indirect
+	github.com/perimeterx/marshmallow v1.1.5 // indirect
+	github.com/speakeasy-api/openapi-overlay v0.9.0 // 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
+)
diff --git a/examples/minimal-server/stdhttp-go-tool/go.sum b/examples/minimal-server/stdhttp-go-tool/go.sum
diff --git a/examples/minimal-server/stdhttp-go-tool/main.go b/examples/minimal-server/stdhttp-go-tool/main.go

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+package api`
	`2`	`+`
	`3`	`+//go:generate go tool github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen -config cfg.yaml ../../api.yaml`