Code Generation Configuration

The codegen.yml file controls how Go types and handlers are generated from your OpenAPI specification.

Mockzilla uses mockzilla-codegen for code generation. codegen.yml is its config file, so every key of its configuration reference works here. Paths in it are relative to setup/.

Location #

Place codegen.yml in the setup/ directory:

services/petstore/
├── gen.go              # Generated on every run
├── register.go         # Generated on every run: wires the service into mockzilla
├── service.go          # Written once, yours to edit
└── setup/
    ├── codegen.yml     # Code generation settings
    ├── config.yml      # Service configuration
    └── openapi.yml     # OpenAPI specification

Default Configuration #

The default codegen.yml generated by the service command:

package: petstore
models:
  int-type: int64
  descriptions: false
  validation:
    response: true
server:
  framework: chi
  validation:
    request: true
    response: false
  scaffold:
    service: ../service.go
output:
  file: ../gen.go

What mockzilla adds #

When the config has a server block, mockzilla adds to the generated code:

• a GenerateResponse field on the request options of every operation, which makes a mock response that satisfies the spec
• register.go, which registers the service with mockzilla and adds NewFactory and the Generate<Op>Response and Generate<Op>Request functions

The scaffold keys write mockzilla's own files instead of the generator's:

server:
  scaffold:
    service: ../service.go         # written once: newService(params) and a method per operation
    middleware: ../middleware.go   # written once: getMiddleware() returns the service's middleware
    main: ../server/main.go        # a standalone server for this one service
    port: 8080
    timeout: 30s

register.go calls newService(params) and serves the *service it returns. A method that returns nil, nil answers with the generated mock response. With overwrite: true the service and middleware files are written on every run.

Filtering Operations #

spec:
  filter:
    include:
      operation-ids: [GetPets, CreatePet]
      tags: [pets]
      paths: [/pets, /pets/{id}]
    exclude:
      operation-ids: [DeletePet]

Overlays #

spec:
  overlays: [custom1.yml, custom2.yml]

The overlays apply to the generated code and, at runtime, to the spec the service serves.

Custom Configuration #

You can provide a custom codegen.yml when generating services:

go run github.com/mockzilla/mockzilla/v2/cmd/gen/service@latest \
  -name petstore \
  -codegen-config ./my-codegen.yml \
  https://petstore3.swagger.io/api/v3/openapi.json

The custom config is merged with the default template, key by key.