# apigenie-generator server go

Source: https://apigenie.pl/docs/reference/generator/server-go
Part of the reference of [apigenie-generator](https://apigenie.pl/docs/reference/generator.md).
Its other pages: [Conformance results](https://apigenie.pl/docs/reference/generator/conformance.md), [docs](https://apigenie.pl/docs/reference/generator/docs.md), [data](https://apigenie.pl/docs/reference/generator/data.md), [schema zod](https://apigenie.pl/docs/reference/generator/schema-zod.md), [client csharp](https://apigenie.pl/docs/reference/generator/client-csharp.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir.md), [client fetch](https://apigenie.pl/docs/reference/generator/client-fetch.md), [client go](https://apigenie.pl/docs/reference/generator/client-go.md), [client java](https://apigenie.pl/docs/reference/generator/client-java.md), [client python](https://apigenie.pl/docs/reference/generator/client-python.md), [client rust](https://apigenie.pl/docs/reference/generator/client-rust.md), [client swift](https://apigenie.pl/docs/reference/generator/client-swift.md), [server aspnet](https://apigenie.pl/docs/reference/generator/server-aspnet.md), [server axum](https://apigenie.pl/docs/reference/generator/server-axum.md), [server express](https://apigenie.pl/docs/reference/generator/server-express.md), [server fastapi](https://apigenie.pl/docs/reference/generator/server-fastapi.md), [server hummingbird](https://apigenie.pl/docs/reference/generator/server-hummingbird.md), [server mcp](https://apigenie.pl/docs/reference/generator/server-mcp.md), [server orpc](https://apigenie.pl/docs/reference/generator/server-orpc.md), [server phoenix](https://apigenie.pl/docs/reference/generator/server-phoenix.md), [server spring](https://apigenie.pl/docs/reference/generator/server-spring.md), [server vapor](https://apigenie.pl/docs/reference/generator/server-vapor.md), [client csharp](https://apigenie.pl/docs/reference/generator/client-csharp-asyncapi.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir-asyncapi.md), [client go](https://apigenie.pl/docs/reference/generator/client-go-asyncapi.md), [client java](https://apigenie.pl/docs/reference/generator/client-java-asyncapi.md), [client kafkajs](https://apigenie.pl/docs/reference/generator/client-kafkajs.md), [client python](https://apigenie.pl/docs/reference/generator/client-python-asyncapi.md), [client ws](https://apigenie.pl/docs/reference/generator/client-ws.md), [server aspnet](https://apigenie.pl/docs/reference/generator/server-aspnet-asyncapi.md), [server faststream](https://apigenie.pl/docs/reference/generator/server-faststream.md), [server go](https://apigenie.pl/docs/reference/generator/server-go-asyncapi.md), [server kafkajs](https://apigenie.pl/docs/reference/generator/server-kafkajs.md), [server phoenix](https://apigenie.pl/docs/reference/generator/server-phoenix-asyncapi.md), [server spring](https://apigenie.pl/docs/reference/generator/server-spring-asyncapi.md), [server ws](https://apigenie.pl/docs/reference/generator/server-ws.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir-protobuf.md), [server elixir-grpc](https://apigenie.pl/docs/reference/generator/server-elixir-grpc.md), [server absinthe](https://apigenie.pl/docs/reference/generator/server-absinthe.md).

[Tier 1](/docs/reference/generator/conformance#tiers) · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · [Verification](#verification)

Generate a Go server for the `net/http` router of Go 1.22 from an OpenAPI document.

From an AsyncAPI document, the command generates a Go Kafka application instead; see
[`apigenie-generator server go` (AsyncAPI)](/docs/reference/generator/server-go-asyncapi).

## Usage

```sh
apigenie-generator server go [...OPTIONS] INPUT_FILE
```

## Description

The generator writes a Go package whose code uses the standard library only. Its names and layering
follow [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen) (the `std-http-server` and
`strict-server` targets), so code written against one of them is easy to move to the other.

| File | Contents |
| ---- | -------- |
| `types.gen.go` | the types of the component schemas the operations use, and of their inline schemas |
| `server.gen.go` | `ServerInterface`, the parameters structs, `ServerInterfaceWrapper`, `Operations`, `SecuritySchemes` and `HandlerWithOptions` |
| `strict.gen.go` | `StrictServerInterface`, the request and response objects, and `NewStrictHandler` |
| `senders.gen.go` | since 0.12.0, `WebhookSender` and the senders of the callbacks, for documents that have webhooks or callbacks |
| `spec.gen.go`, `openapi.yaml` | the OpenAPI document, embedded with `//go:embed` (`RawSpec()`) |
| `runtime_*.gen.go` | parameter binding, validation, problem details, `Nullable[T]`, `Date`, multipart helpers, the writers of server-sent events and JSON Lines, and the request encoding of the senders |
| `go.mod`, `cmd/<package>/main.go` | with `layout: module` (and `main: true`) |

There are two ways to implement the server:

- **`ServerInterface`**: one method per operation receives the `http.ResponseWriter`, the request,
  the path parameters and a struct with the query, header and cookie parameters, bound and
  validated. The method decodes the body and writes the response.
- **`StrictServerInterface`**: one method per operation receives a request object (parameters and
  decoded, validated body) and returns a response object, e.g. `GetPet200JSONResponse`, with its
  status, typed headers and body. `NewStrictHandler` turns it into a `ServerInterface`.

```go
mux := http.NewServeMux()
api.HandlerWithOptions(api.NewStrictHandler(server, nil), api.StdHTTPServerOptions{
    BaseURL:         "/api/v1",
    BaseRouter:      mux,
    SecurityHandler: authenticator, // runs before parameters are bound
})
log.Fatal(http.ListenAndServe(":8080", mux))
```

`HandlerWithOptions` registers one pattern per operation, e.g. `GET /pets/{petId}`, so routing,
`405 Method Not Allowed` (with `Allow`) and `HEAD` requests are handled by `http.ServeMux`:

- paths ending with `/` are registered as `/{$}`, so that they don't match the paths below them;
- path parameters whose names aren't Go identifiers (`{pet-id}`) are renamed, and parameters
  sharing a path segment with other text (`/files/{name}.{ext}`) are split out of it;
- patterns `http.ServeMux` can't register together (it panics), such as `GET /a/{x}/b` and
  `GET /a/b/{y}`, are served through one pattern generalizing them, which sends each request to
  the most specific operation. `route_conflicts: error` reports them as errors instead;
- since 0.12.0, an operation with its own server is registered below the path of that server's
  URL instead of `BaseURL`. Its server is the first of the `servers` of the operation, or else of
  its path item, with the default values of its variables: `POST /v2/shipments/imports` for
  `https://uploads.example.com/v2`. A URL without a path registers the operation at the root
  (`GET /health` for `https://status.example.com`). The `Server` and `ServerPath` fields of the
  operation's entry in `Operations` hold the URL and its path.

Since 0.12.0, operations marked `x-internal: true` (on the operation or its path item) are left
out, and so are webhooks and callback requests marked so. `internal_operations: true` generates
them too. `include_tags` and `exclude_tags` don't apply to webhooks; callbacks follow their
operation.

### Streams

Since 0.12.0, responses of `text/event-stream` get an `Events` field, a
`<-chan ServerSentEvent[T]`. `ServerSentEvent` has the fields `ID`, `Event`, `Retry`
(milliseconds) and `Data`. `ID` and `Event` aren't written when empty, nor `Retry` unless
it is positive. `T` is the type of the `contentSchema` of
the `data` property of the `itemSchema`. A `data` property without `contentSchema`, or a response
without `itemSchema`, gives `string`. An `itemSchema` without a `data` property is the type of
`Data` itself. A `string` is written as is, other types as JSON.

Responses of `application/jsonl`, `application/x-jsonlines` and `application/x-ndjson` with an
`itemSchema` get an `Items` channel of the item type. Each event or line is written and flushed as
it arrives, until the handler closes the channel; when the channel is nil, `Body` is written
instead. A write stops at the first error, for example when the client disconnects, so the
producer must stop when the request's context is done:

```go
func (s *server) GetTrackingEvents(ctx context.Context, request api.GetTrackingEventsRequestObject) (api.GetTrackingEventsResponseObject, error) {
    events := make(chan api.ServerSentEvent[api.TrackingEvent])
    go func() {
        defer close(events)
        for event := range s.tracking.Watch(ctx, request.ShipmentID) {
            select {
            case events <- api.ServerSentEvent[api.TrackingEvent]{Event: "tracking", Data: event}:
            case <-ctx.Done():
                return
            }
        }
    }()
    return api.GetTrackingEvents200TextEventStreamResponse{Events: events}, nil
}
```

### Webhooks and callbacks

Since 0.12.0, `WebhookSender` has one method per webhook, named after its `operationId`
(`OnShipmentDelivered`), or after the webhook's name and method without one. Each callback of an
operation gets a sender type named after the operation and the callback, e.g.
`CreateShipmentStatusChangedCallback`. Its method is `Send`, or one method per HTTP method (`Post`,
`Put`) when the callback has several.

A method takes a `context.Context` and the URL to send to. Then it takes the parameters struct,
when the request has query, header or cookie parameters, and the body, when it has one. An
optional JSON body is a pointer, unless its type is a slice, a map or `any`, and is sent only when
it is set. It returns the `*http.Response`, whose body the caller closes. The caller gives the
URL: the subscriber's, or the value the callback expression selects from the request, which the
method's doc comment names (`given by {$request.body#/callbackUrl}`). Path parameters are part of
that URL. Parameters are serialized like those of [`client go`](/docs/reference/generator/client-go), in their style:

```go
sender := api.WebhookSender{Client: httpClient} // http.DefaultClient when nil
params := api.OnShipmentDeliveredParams{CarpetExpressSignature: signature}
if err := params.Validate(); err != nil {
    return err
}
response, err := sender.OnShipmentDelivered(ctx, subscription.URL, params, event)
if err != nil {
    return err
}
defer response.Body.Close()
```

A sender sends the first media type of the request body it can encode: JSON, text, binary, or a
form without declared fields (`url.Values`). A request body with only other media types,
multipart included, is left out, and the generator warns. For a webhook `orderForm`, the warning
is `The request body of POST orderForm has no media type the sender can encode (JSON, text, binary
or a form without declared fields); the request is sent without a body`.

### Types

- Optional properties are pointers with `omitempty`; slices, maps and `any` stay values.
  `optional_fields: omitzero` uses values with `omitzero` (Go 1.24).
- Optional properties that can be null are `Nullable[T]`, which tells absent, null and set values
  apart; required ones are pointers. `nullable_type: pointer` uses pointers for both.
- Required properties that are `readOnly` or `writeOnly` are pointers, as they are absent from
  requests or responses.
- Structs that would contain themselves hold pointers.
- Enums are defined types with constants named after the type and the value
  (`PetStatusAvailable`), `PetStatusValues()`, `IsValid()` and `Validate()`.
- `oneOf` and `anyOf` schemas are structs with one pointer per variant. With a discriminator, the
  value goes to the variant its property selects: through the `mapping`, the name of the schema
  or the value the schema gives the property (`const`); other values go to the `defaultMapping`
  variant (`x-defaultMapping` in 3.0 and 3.1 documents), or are kept in `Raw`. Without a
  discriminator, the value goes to the first variant it decodes into without unknown properties
  and validates against.
- since 0.12.0, `prefixItems` tuples without `items`, or with `items: false`, are slices. When
  every position is a reference or a scalar of the same Go type and nullability, it's a slice of
  that type (`[]float64`), and `Validate()` checks each position; otherwise it's `[]any`. With
  `items: false`, `Validate()` checks the length too.
- since 0.12.0, a schema whose only properties are `patternProperties` is a map. With one pattern
  and `additionalProperties: false`, it maps to the pattern's type. When the patterns and a
  schema of `additionalProperties` have the same type, it maps to that type; otherwise to `any`.
  `Validate()` checks the keys against the patterns when `additionalProperties` is `false`. It
  checks the values of each pattern, and those of the other keys against `additionalProperties`,
  when their type has a `Validate()` method, or is a boolean, an integer, a number or a
  string.
- `allOf` schemas are merged into one struct; an `anyOf` or `oneOf` whose members only list
  required properties (`anyOf: [{required: [email]}, {required: [phone]}]`) is checked by
  `Validate()`.
- `additionalProperties` are kept in an `AdditionalProperties` map.
- `date-time` strings are `time.Time`, `date` strings `Date`, `byte` and `binary` strings
  `[]byte` (files in multipart bodies).

### Validation

Every type has a `Validate()` method that checks the constraints of its schema. The checks cover
lengths, patterns, bounds, `multipleOf`, items, tuple positions, properties, pattern properties,
`if`/`then`/`else`, `dependentRequired`, `dependentSchemas` and enums (the tuple, pattern and
condition checks since 0.12.0), and since 0.12.0 `not` and draft-07 `dependencies` within the same
limits as `if`/`then`/`else` (see below). They also cover the `email`, `uuid`, `uri`, `hostname`, `ipv4`,
`ipv6`, `date`, `date-time` and `time` formats; `contentEncoding: base64` strings are `[]byte`.
Parameters and request bodies are validated before the handlers are called, and failures are
answered with [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details listing the failed
checks:

```json
{"title":"Bad Request","status":400,"detail":"The request is not valid.",
 "errors":[{"path":"limit","check":"maximum","message":"must be less than or equal to 100"}]}
```

`DefaultErrorHandler` maps errors to statuses: 400 for parameters and bodies, 413 for bodies
larger than `max_body_bytes`, 415 for unsupported media types, the status of a `SecurityError`
(401 by default) or of an error implementing `StatusCode() int`, and 500 otherwise.

### Extensions

| Extension | Effect |
| --------- | ------ |
| `x-go-name` | name of the type of a schema, or of the field of a property |
| `x-go-type` | Go type of a schema, e.g. `decimal.Decimal`; with `x-go-type-import: {path: ...}` for its package |
| `x-go-type-skip-optional-pointer` | the optional property isn't a pointer |
| `x-go-json-ignore` | the field gets the tag `json:"-"` |
| `x-omitempty` | `true` or `false` overrides the `omitempty` of the field |
| `x-enum-varnames`, `x-enumNames` | names of the enum constants |
| `x-enum-descriptions` | comments of the enum constants |
| `x-apigenie.codegen.name` | name of the type of a component schema, when it has no `x-go-name` |
| `x-apigenie.codegen.action-name` | name of the handler method of an operation without an `operationId` (with the default `action_naming`, which lists `id` first) |
| `x-apigenie.codegen.disabled` | `true` on an operation or its path item leaves the operation out |
| `x-defaultMapping` | `defaultMapping` of a discriminator in OpenAPI 3.0 and 3.1 documents: the schema of the values whose discriminator value isn't mapped |

The extensions can live in an overlay for this target instead of in the document, e.g.
`go.overlay.yaml`:

```yaml
overlay: 1.0.0
info:
  title: Go types
  version: 1.0.0
actions:
  - target: $.components.schemas.Pet
    update:
      x-go-name: Animal
  - target: $.components.schemas.Pet.properties.price
    update:
      x-go-type: decimal.Decimal
      x-go-type-import:
        path: github.com/shopspring/decimal
```

```sh
apigenie-generator server go openapi.yaml --overlay go.overlay.yaml -o out
```

### Limitations

- Links aren't generated: they describe follow-up requests of clients.
- The senders don't validate what they send: call `Validate()` on the parameters struct and the
  body first. Multipart bodies aren't sent.
- Operations with their own server that share a pattern with other operations (see
  `route_conflicts`) are served below `BaseURL`, and the host of the server isn't checked.
- Request streams are `io.Reader` bodies; only responses are typed streams.
- `Validate()` doesn't check `unevaluatedProperties`. It checks `if`/`then`/`else`, `not`,
  `dependentSchemas` and the schemas of draft-07 `dependencies` only when their schemas use
  `required` and the `const` and `enum` of properties, and skips the others.
- XML bodies are passed as streams (`io.Reader`), and form or multipart responses too.
- Patterns using lookaround or backreferences, which Go's `regexp` package doesn't support, aren't
  checked (a warning says so). Patterns are compiled when first used.
- `allOf` schemas are flattened: there are no type hierarchies.
- Exported names of the runtime (`Problem`, `Date`, `File`, `Nullable`, `Operation`, ...) are
  reserved: schemas with these names get numbered types, e.g. `Problem2`.
- The input must be an OpenAPI 3.0, 3.1 or 3.2 document or, since 0.12.0, a Swagger 2.0 document
  (see [Swagger 2.0 input](/docs/reference/generator#swagger-20-input)); bundle documents
  referencing other files with `apigenie bundle`.

## Options

### -c, --config

Path to the configuration file to use. See the "Configuration" section for more information.

### --overlay OVERLAY

Path to an OpenAPI Overlay (1.0 to 1.2) applied to the input before generating, e.g. one setting the
extensions of the "Extensions" section. Can be repeated: the overlays apply in order, after those
listed under `commands.generate.server_go.overlay` in the configuration file (with paths relative to
it). Warnings and errors about a value an overlay set point to the overlay.

### --strict

Makes an overlay action whose target selects nothing an error (exit status 2, nothing is generated)
instead of a warning (`OVERLAY:LINE:COL: action #N (TARGET) selects no nodes.`).

### --check

Writes nothing: compares what the generator would write with the output directory, prints the
files that would be created or changed, and exits with 1 when there are any (since 0.12.0). See
[Check that generated code is up to date](/docs/reference/generator#check-that-generated-code-is-up-to-date).

### -o, --output

Directory where the package is generated.

### --package-name

Name of the Go package. Defaults to the name of the output directory (`api` when it isn't a valid
package name).

### --package-version

Ignored: Go packages have no version.

### -p, --property NAME=VALUE

Sets a generator option (see below), e.g. `-p layout=module`. Options given on the command line
take precedence over the configuration file. Lists are comma-separated (`-p include_tags=pets,store`)
and mappings too (`-p type_mappings=uuid=github.com/google/uuid.UUID`).

## Configuration

```yaml
version: '1.0'
commands:
  generate:
    server_go:
      package: petstore
      layout: module
      module: github.com/acme/petstore
      type_mappings:
        uuid: github.com/google/uuid.UUID
```

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| `package` | string | name of the output directory | Name of the Go package; also set by `--package-name`. |
| `layout` | `package` or `module` | `package` | `module` also writes `go.mod`, making the output a module of its own. |
| `module` | string | `example.com/<package>` | Module path written to `go.mod`. |
| `main` | boolean | `false` | With `layout: module`, writes `cmd/<package>/main.go` running a server whose operations answer 501, unless the file exists. |
| `generate` | list of `types`, `server`, `strict` | all | Files to write. `strict` requires `server`, which requires `types`. |
| `embedded_spec` | boolean | `true` | Writes `openapi.yaml` and `spec.gen.go` embedding it. |
| `optional_fields` | `pointer` or `omitzero` | `pointer` | Optional properties as pointers with `omitempty`, or as values with `omitzero` (Go 1.24). |
| `nullable_type` | `tristate` or `pointer` | `tristate` | Optional nullable properties as `Nullable[T]`, or as pointers. |
| `include_tags` | list of strings | | Generates only the operations with one of these tags. |
| `exclude_tags` | list of strings | | Skips the operations with one of these tags. |
| `skip_prune` | boolean | `false` | Keeps the component schemas that no generated operation uses. |
| `internal_operations` | boolean | `false` | Also generates the operations marked `x-internal: true` (on the operation or its path). |
| `validate_requests` | boolean | `true` | Validates parameters and request bodies against their schemas. |
| `validate_responses` | boolean | `false` | Validates the bodies of strict responses before writing them (500 when they aren't valid). |
| `route_conflicts` | `warn` or `error` | `warn` | Serve the patterns `http.ServeMux` can't register together through a shared pattern, or report them as errors. |
| `initialisms` | list of strings | | Words written in upper case in identifiers, besides `ID`, `URL`, `HTTP`, `JSON` and the other initialisms of golint. |
| `type_mappings` | map of strings | | Go types of string formats or `x-go-type` names, e.g. `uuid: github.com/google/uuid.UUID`. |
| `max_body_bytes` | integer | `0` (no limit) | Largest request body the strict server reads (413 beyond). |
| `max_multipart_memory` | integer | `33554432` | Memory multipart bodies may take before their files are stored on disk. |
| `action_naming` | list of `id`, `extension`, `url` | `id, extension, url` | Where operation names come from, in order of preference. |

## Verification

The [codegen conformance suite](/docs/reference/generator#conformance-checks) runs this target on the Carpet Express OpenAPI fixture. Level 1 compares the output with its snapshots and checks each feature, Level 2 runs the language's type checker and linter, and Level 3 runs the generated code in contract tests against the fixture. [All targets](/docs/reference/generator/conformance#openapi).

This target's support tier is [Tier 1](/docs/reference/generator/conformance#tiers). It goes through all three levels before every release, with the goal of supporting every feature of the fixture. Its unsupported features are worked on first.

| Results | Level 1 | Level 2 | Level 3 |
| --- | --- | --- | --- |
| Release 0.12.0 | ✓ snapshots of 3.2, 3.1, 3.0, 2.0; 3.2: 39 supported, 0 not yet | ✓ pass (go version go1.22.5 linux/amd64) | ✓ 70 of 77 operations pass, 2 known failures (go) |
| Development version | ✓ snapshots of 3.2, 3.1, 3.0, 2.0; 3.2: 39 supported, 0 not yet | runs before a release | runs before a release, 2 known failures |
