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 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.
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:

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 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 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 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); 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.

ResultsLevel 1Level 2Level 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 yetruns before a releaseruns before a release, 2 known failures
Was this helpful?