mockzilla-codegen

Go models, HTTP servers, clients and MCP tools from OpenAPI 3.0, 3.1 and 3.2 specs.

Why this one

Every generator works on the petstore. This one works on yours. The specs of Stripe, GitHub, OpenAI
and Adyen generate, build and run, and so do 2,200+ other real-world specs.

Specs

• OpenAPI 3.1 and 3.2, next to 3.0.
• oneOf and anyOf, with or without a discriminator, nested in each other. In a body, a
  parameter, a header or a form field.
• allOf merged into one struct, its limits combined to the strictest.
• Every inline object gets a named type, however deep. No anonymous structs.
• $ref into other files, and overlays.
• A part that cannot be generated gets a warning and is left out. The rest is written.

Parameters and bodies

• Parameters in every style OpenAPI defines, deepObject and the 3.2 cookie style included.
• Defaults filled in for parameters the request leaves out.
• JSON, form and multipart bodies, nested objects included. Binary bodies stream.

Idiomatic Go

• Fields in the order of the spec. Name clashes resolved for you.
• A pointer only where a value can be missing, never on a slice or map.
• runtime.Nullable[T] tells null from absent, so a PATCH can clear a value or leave it as it
  is. Turn it on for the whole spec or for one field.
• Validation in plain Go: required fields, patterns, limits, multipleOf, uniqueItems. The
  server can check every request and response with it.
• An error response the spec documents is a Go error, on the server and on the client.
• One file, many files, or a package per part. Any block of the templates can be replaced.

No heavy dependencies

• Generated code imports the standard library, your router, and a runtime package that uses only
  the standard library.
• No YAML parser, logger or third-party JSON library ends up in your binary. Plug one in if you
  want it.

Server and client

• 14 routers, net/http's ServeMux among them. Your service stays the same on each.
• Hooks for OpenTelemetry on server and client: middleware around each operation, and the HTTP
  client you pass in. Both see the operation name (observability).
• MCP tools over the client, so an AI assistant can call your API.

Coming from another generator? The migration guides map every flag, config key
and extension.

Quick start

Go 1.26 or newer.

go get -tool github.com/mockzilla/mockzilla-codegen/cmd/mockzilla-codegen
go tool mockzilla-codegen generate openapi.yaml               # models in ./gen.go
go tool mockzilla-codegen generate openapi.yaml -server chi   # and a chi server
go tool mockzilla-codegen generate -c codegen.yaml            # what the config lists

Example

This spec:

paths:
  /pets/{id}:
    get:
      operationId: getPet
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses:
        "200":
          description: ok
          content: {application/json: {schema: {$ref: "#/components/schemas/Pet"}}}
components:
  schemas:
    Pet:
      type: object
      required: [id, name]
      properties:
        id: {type: integer}
        name: {type: string, maxLength: 64}
        tag: {type: string}

gives this, among other code:

type Pet struct {
	ID   int     `json:"id"`
	Name string  `json:"name"`
	Tag  *string `json:"tag,omitempty"`
}

func (p Pet) Validate() error {
	var errs validation.Errors
	errs.Append("name", validation.MaxLength(p.Name, 64))
	return errs.Err()
}

type ServiceInterface interface {
	// GetPet handles GET /pets/{id}.
	GetPet(ctx context.Context, opts *GetPetServiceRequestOptions) (*GetPetResponseData, error)
}

You implement the service. The generated router decodes the request and writes the response:

type pets struct{}

func (pets) GetPet(ctx context.Context, opts *api.GetPetServiceRequestOptions) (*api.GetPetResponseData, error) {
	return api.NewGetPetResponseData(&api.Pet{ID: opts.PathParams.ID, Name: "Rex"}), nil
}

http.ListenAndServe(":8080", api.NewRouter(pets{}))

Docs

Contributing

Issues and pull requests are welcome. CONTRIBUTING.md lists the make targets, the
checks a pull request has to pass, and how to add a router.

License

MIT, see LICENSE. The Go gopher was designed by Renée French and is licensed under
CC BY 4.0. The gopher above is a new drawing of it.