apigenie-generator server go
Tier 1 · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · 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).
Usage
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 (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 thehttp.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.NewStrictHandlerturns it into aServerInterface.
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.ServeMuxcan’t register together (it panics), such asGET /a/{x}/bandGET /a/b/{y}, are served through one pattern generalizing them, which sends each request to the most specific operation.route_conflicts: errorreports 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 theserversof the operation, or else of its path item, with the default values of its variables:POST /v2/shipments/importsforhttps://uploads.example.com/v2. A URL without a path registers the operation at the root (GET /healthforhttps://status.example.com). TheServerandServerPathfields of the operation’s entry inOperationshold 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:
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, in their style:
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 andanystay values.optional_fields: omitzerouses values withomitzero(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: pointeruses pointers for both. - Required properties that are
readOnlyorwriteOnlyare 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()andValidate(). oneOfandanyOfschemas are structs with one pointer per variant. With a discriminator, the value goes to the variant its property selects: through themapping, the name of the schema or the value the schema gives the property (const); other values go to thedefaultMappingvariant (x-defaultMappingin 3.0 and 3.1 documents), or are kept inRaw. Without a discriminator, the value goes to the first variant it decodes into without unknown properties and validates against.- since 0.12.0,
prefixItemstuples withoutitems, or withitems: 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), andValidate()checks each position; otherwise it’s[]any. Withitems: false,Validate()checks the length too. - since 0.12.0, a schema whose only properties are
patternPropertiesis a map. With one pattern andadditionalProperties: false, it maps to the pattern’s type. When the patterns and a schema ofadditionalPropertieshave the same type, it maps to that type; otherwise toany.Validate()checks the keys against the patterns whenadditionalPropertiesisfalse. It checks the values of each pattern, and those of the other keys againstadditionalProperties, when their type has aValidate()method, or is a boolean, an integer, a number or a string. allOfschemas are merged into one struct; ananyOforoneOfwhose members only list required properties (anyOf: [{required: [email]}, {required: [phone]}]) is checked byValidate().additionalPropertiesare kept in anAdditionalPropertiesmap.date-timestrings aretime.Time,datestringsDate,byteandbinarystrings[]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 problem details listing the failed
checks:
{"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:
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
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 belowBaseURL, and the host of the server isn’t checked. - Request streams are
io.Readerbodies; only responses are typed streams. Validate()doesn’t checkunevaluatedProperties. It checksif/then/else,not,dependentSchemasand the schemas of draft-07dependenciesonly when their schemas userequiredand theconstandenumof 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
regexppackage doesn’t support, aren’t checked (a warning says so). Patterns are compiled when first used. allOfschemas 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); 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.
-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
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 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.
This target's support tier is Tier 1. 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 |