oapi-codegen · mromaszewicz · Mar 4, 2026
@@ -23,7 +23,6 @@ require (
 	github.com/oapi-codegen/runtime v1.2.0
 	github.com/oapi-codegen/testutil v1.1.0
 	github.com/stretchr/testify v1.11.1
-	golang.org/x/lint v0.0.0-20241112194109-818c5a804067
 )
 
 require (

@@ -323,9 +323,6 @@ golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
 golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
 golang.org/x/exp v0.0.0-20240404231335-c0f41cb1a7a0 h1:985EYyeCOxTpcgOTJpflJUwOeEz0CQOdPt73OzpE9F8=
 golang.org/x/exp v0.0.0-20240404231335-c0f41cb1a7a0/go.mod h1:/lliqkxwWAhPjf5oSOIJup2XcqJaw8RGS6k3TGEc7GI=
-golang.org/x/lint v0.0.0-20241112194109-818c5a804067 h1:adDmSQyFTCiv19j015EGKJBoaa7ElV0Q1Wovb/4G7NA=
-golang.org/x/lint v0.0.0-20241112194109-818c5a804067/go.mod h1:3xt1FjdF8hUf6vQPIChWIBhFzV8gjjsPE/fR3IyQdNY=
-golang.org/x/mod v0.1.1-0.20191105210325-c90efee705ee/go.mod h1:QqPTAvyqsEbceGzBzNggFXnrqF1CaUcvgkdR5Ot7KZg=
 golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.5.1/go.mod h1:5OXOZSfqPIIbmVBIIKWRFfZjPR0E5r58TLhUjH0a2Ro=
 golang.org/x/mod v0.33.0 h1:tHFzIWbBifEmbwtGz65eaWyGiGZatSrT9prnU8DbVL8=
@@ -379,7 +376,6 @@ golang.org/x/time v0.14.0 h1:MRx4UaLrDotUKUdCIqzPC48t1Y9hANFKIRpNx+Te8PI=
 golang.org/x/time v0.14.0/go.mod h1:eL/Oa2bBBK0TkX57Fyni+NgnyQQN4LitPmob2Hjnqw4=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
-golang.org/x/tools v0.0.0-20200130002326-2f3ba24bd6e7/go.mod h1:TB2adYChydJhpapKDTa4BR/hXlZSLoq2Wpct/0txZ28=
 golang.org/x/tools v0.0.0-20201224043029-2b0845dc783e/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
 golang.org/x/tools v0.1.9/go.mod h1:nABZi5QlRsZVlzPpHl034qft6wpY4eDcsTt5AaioBiU=
 golang.org/x/tools v0.42.0 h1:uNgphsn75Tdz5Ji2q36v/nsFSfR/9BRFvqhGBaJGd5k=

@@ -1,16 +1,107 @@
-OpenAPI Code Generation Example
--------------------------------
+# Petstore Expanded Example
 
-This directory contains an example server using our code generator which implements
-the OpenAPI [petstore-expanded](https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/petstore-expanded.yaml)
-example.
+This example demonstrates [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen) generating server stubs for 9 different Go HTTP frameworks from a single [OpenAPI 3.0 spec](petstore-expanded.yaml) (the canonical Petstore Expanded example).
 
-This is the structure:
-- `api/`: Contains the OpenAPI 3.0 specification
-- `api/petstore/`: The generated code for our pet store handlers
-- `internal/`: Pet store handler implementation and unit tests
-- `cmd/`: Runnable server implementing the OpenAPI 3 spec.
+## Directory Structure
 
-To generate the handler glue, run:
+```
+petstore-expanded/
+├── petstore-expanded.yaml          # Shared OpenAPI spec
+├── common/
+│   ├── generate.go                 # go:generate for shared model types
+│   ├── models.cfg.yaml             # Codegen config: models only
+│   ├── models/
+│   │   └── models.gen.go           # Generated model types (shared by all variants)
+│   ├── store/
+│   │   └── store.go                # Framework-agnostic CRUD business logic
+│   └── client/
+│       ├── main.go                 # CLI test client
+│       ├── testclient/
+│       │   └── testclient.go       # Reusable test client (shared by integration tests)
+│       └── openapi/
+│           ├── generate.go         # go:generate for client
+│           ├── client.cfg.yaml     # Codegen config: client only
+│           └── client.gen.go       # Generated HTTP client
+├── chi/                            # Chi (net/http compatible)
+├── gorilla/                        # Gorilla/mux (net/http compatible)
+├── stdhttp/                        # stdlib net/http (Go 1.22+ ServeMux)
+├── echo/                           # Echo v4
+├── echo-v5/                        # Echo v5 (requires Go 1.25+, separate module)
+├── gin/                            # Gin
+├── fiber/                          # Fiber
+├── iris/                           # Iris
+└── strict/                         # Strict server (Chi + typed request/response objects)
+```
 
-    go run cmd/oapi-codegen/oapi-codegen.go --package petstore examples/petstore-expanded/petstore-expanded.yaml  > examples/petstore-expanded/petstore.gen.go
+Each server variant follows the same pattern:
+- `api/server.cfg.yaml` — codegen config generating the server interface and embedded spec
+- `api/generate.go` — `//go:generate` directive for the server code
+- `api/petstore-server.gen.go` — generated server boilerplate
+- `server/server.go` — hand-written `ServerInterface` implementation delegating to `common/store`
+- `server/setup.go` — factory function that creates a fully configured server/app
+- `petstore.go` — `main()` wiring (thin wrapper around `setup.go`)
+- `integration/main.go` — integration test program using the shared test client
+
+## Generating Code
+
+From the `examples/` directory (or repository root with `make generate`):
+
+```sh
+# Generate shared models and client
+cd examples/petstore-expanded/common && go generate ./...
+
+# Generate a specific server variant
+cd examples/petstore-expanded/chi/api && go generate ./...
+```
+
+For `echo-v5` (separate Go module):
+
+```sh
+cd examples/petstore-expanded/echo-v5/api && go generate ./...
+```
+
+## Running a Server
+
+```sh
+cd examples/petstore-expanded/chi
+go run . --port 8080
+```
+
+Replace `chi` with any variant: `gorilla`, `stdhttp`, `echo`, `echo-v5`, `gin`, `fiber`, `iris`, `strict`.
+
+## Integration Tests
+
+Each variant has an integration test program that starts the server on a random port, runs all CRUD operations via the generated HTTP client, and shuts down cleanly:
+
+```sh
+cd examples/petstore-expanded
+go run ./chi/integration/
+go run ./gorilla/integration/
+go run ./stdhttp/integration/
+go run ./strict/integration/
+go run ./gin/integration/
+go run ./echo/integration/
+go run ./fiber/integration/
+go run ./iris/integration/
+```
+
+For the separate-module variant:
+
+```sh
+cd examples/petstore-expanded/echo-v5
+go run ./integration/
+```
+
+## CLI Test Client
+
+The test client can also be run manually against a server you start in a separate terminal:
+
+```sh
+# Terminal 1: start any server variant
+cd examples/petstore-expanded/chi && go run .
+
+# Terminal 2: run the test client
+cd examples && go run ./petstore-expanded/common/client/ --port 8080
+```
+
+The client verifies: add pets, find by ID, 404 on missing pet, list/filter by tag, delete, and empty list after deletion.
@@ -0,0 +1,3 @@
+package api
+
+//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen --config=server.cfg.yaml ../../petstore-expanded.yaml
@@ -0,0 +1,11 @@
+# yaml-language-server: $schema=../../../../../configuration-schema.json
+package: api
+generate:
+  chi-server: true
+  embedded-spec: true
+compatibility:
+  apply-chi-middleware-first-to-last: true
+additional-imports:
+  - package: github.com/oapi-codegen/oapi-codegen/v2/examples/petstore-expanded/common/models
+    alias: .
+output: petstore-server.gen.go
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		package api

		//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen --config=server.cfg.yaml ../../petstore-expanded.yaml