Todo list server

The todo-list example is the canonical go-swagger server: a small CRUD API generated from a spec, wired to a trivial in-memory store. It’s the best place to see what swagger generate server produces and which files you’re expected to edit.

Prefer a step-by-step build? Start with the todo-list tutorial. This page is the reference tour of the finished example.

The spec

Two definitions drive everything: an item (with a required, minLength: 1 description and a read-only id) and a generic error.

item:
  type: object
  required:
    - description
  properties:
    id:
      type: integer
      format: int64
      readOnly: true
    description:
      type: string
      minLength: 1
    completed:
      type: boolean
error:
  type: object
  required:
    - message
  properties:
    code:
      type: integer
      format: int64
    message:
      type: string

Full source: todo-list/swagger.yml

The readOnly: true on id means the server assigns it — clients that send one have it ignored on create.

Generated models

Each definition becomes a Go struct. Note how the spec constraints map onto the type: description is required and minLength: 1, so it’s generated as a non-pointer-safe *string carrying validation, while the read-only id is a plain int64.

type Item struct {

	// completed
	Completed bool `json:"completed,omitempty"`

	// description
	// Required: true
	// Min Length: 1
	Description *string `json:"description"`

	// id
	// Read Only: true
	ID int64 `json:"id,omitempty"`
}

Full source: todo-list/models/item.go

The generator also emits the validation methods that enforce the spec’s constraints at runtime — here the description field’s required and minLength: 1 rules, wired straight from the spec. You never hand-write this:

func (m *Item) validateDescription(formats strfmt.Registry) error {

	if err := validate.Required("description", "body", m.Description); err != nil {
		return err
	}

	if err := validate.MinLength("description", "body", *m.Description, 1); err != nil {
		return err
	}

	return nil
}

Full source: todo-list/models/item.go

Wiring the handlers

restapi/configure_todo_list.go is the one file you edit — it’s marked safe to edit and survives regeneration. The generated scaffold leaves each handler returning 501 Not Implemented; you replace those with real logic. Here’s the implemented version from the tutorial’s server-complete, backing the store with a map:

api.TodosAddOneHandler = todos.AddOneHandlerFunc(func(params todos.AddOneParams) middleware.Responder {
	if err := addItem(params.Body); err != nil {
		return todos.NewAddOneDefault(500).WithPayload(&models.Error{Code: 500, Message: conv.Pointer(err.Error())})
	}
	return todos.NewAddOneCreated().WithPayload(params.Body)
})
api.TodosDestroyOneHandler = todos.DestroyOneHandlerFunc(func(params todos.DestroyOneParams) middleware.Responder {
	if err := deleteItem(params.ID); err != nil {
		return todos.NewDestroyOneDefault(500).WithPayload(&models.Error{Code: 500, Message: conv.Pointer(err.Error())})
	}
	return todos.NewDestroyOneNoContent()
})

Full source: tutorials/todo-list/server-complete/restapi/configure_todo_list.go

Each response constructor (NewAddOneCreated, NewDestroyOneNoContent, …) is generated from a response you declared in the spec, so the compiler keeps your handlers honest against the contract.

Running it

The generated server listens on a Unix socket, HTTP and HTTPS by default. For a quick local test, enable just the HTTP listener on a fixed port:

$ go run ./todo-list/cmd/todo-list-server --scheme=http --port=8765
serving todo list at http://127.0.0.1:8765

$ curl -i localhost:8765 \
    -H 'Content-Type: application/io.goswagger.examples.todo-list.v1+json' \
    -d '{"description":"go shopping"}'
HTTP/1.1 201 Created
...
{"description":"go shopping","id":1}

See the todo-list README for the full listener matrix (unix/http/https) and TLS options.

Variations

• Strict server — the strict responder interface.
• Custom error handling — shaping error responses.
• Todo list tutorial — build this from scratch.

Strict server

The strict server is generated with --strict-responders. Instead of every handler returning a generic middleware.Responder — which lets you hand back any response, including ones the spec never declared — each operation gets its own responder interface. The compiler then enforces that a handler can only return responses declared for that operation.

The generated responder interface

For each operation, the generator emits a marker interface embedding middleware.Responder. Only the response types declared for addOne implement AddOneResponder, so nothing else can be returned:

type AddOneResponder interface {
	middleware.Responder
	AddOneResponder()
}

Full source: todo-list-strict/restapi/operations/todos/add_one_responses.go

Every generated response for the operation — AddOneCreated, AddOneDefault, AddOneNotImplemented — carries a no-op AddOneResponder() method, which is what admits it to the interface. A FindDefault value, for instance, simply won’t compile inside an addOne handler.

The handler signature

Compare with the default todo-list server, where the handler returns middleware.Responder. Here the return type is the operation-specific todos.AddOneResponder:

if api.TodosAddOneHandler == nil {
	api.TodosAddOneHandler = todos.AddOneHandlerFunc(func(params todos.AddOneParams, principal any) todos.AddOneResponder {
		_ = params
		_ = principal

		return todos.AddOneNotImplemented()
	})
}

Full source: todo-list-strict/restapi/configure_simple_to_do_list_api.go

The scaffold guards each assignment with if … == nil, so you can wire a handler from elsewhere and leave the rest returning NotImplemented. You replace the body with real logic, returning one of the operation’s typed responders.

When to use it

Reach for strict responders when you want the type system to guarantee your handlers stay in sync with the contract — you can’t accidentally return a response shape the spec doesn’t describe. The cost is a little more generated surface (one interface per operation) and slightly more verbose returns.

Related

• Todo list server — the default (non-strict) responder style.
• Custom error handling — returning errors from handlers.

Custom error handling

By default a generated handler returns a middleware.Responder and you build error responses yourself (NewAddOneDefault(500).WithPayload(...)). The todo-list-errors example shows the alternative: generate with --return-errors so handlers may return a plain error, and install a single custom error handler that shapes every error response in one place.

Handlers that return an error

With --return-errors, the handler signature becomes func(params) (middleware.Responder, error). A handler can now short-circuit by returning an error instead of constructing a response:

api.TodosAddOneHandler = todos.AddOneHandlerFunc(
	func(params todos.AddOneParams) (middleware.Responder, error) {
		_ = params

		return nil, errAlreadyExists
	})

Full source: todo-list-errors/restapi/configure_todo_list.go

Here errAlreadyExists is a sentinel the handler returns directly — no response plumbing at the call site.

The centralized error handler

Returned errors flow through api.ServeError, which you can override. This example wires it to a catcher that recognizes the sentinel (with errors.Is), logs it, then defers to the runtime’s default ServeError for the actual HTTP response:

func catcher(w http.ResponseWriter, r *http.Request, err error) {
	if errors.Is(err, errAlreadyExists) {
		slog.Info("we catch custom error! congratulations!")
	}

	oapierrors.ServeError(w, r, err)
}

var errAlreadyExists = errors.New("already exists")

Full source: todo-list-errors/restapi/configure_todo_list.go

Installing it is one line in configureAPI:

api.ServeError = catcher

Because every operation’s error funnels through the same hook, you get one place to classify errors, attach correlation IDs, translate domain errors to status codes, or emit metrics — without repeating that logic in each handler.

When to use it

Use returned errors when your handlers naturally surface Go error values (a data layer, a validation step) and you’d rather map them to responses centrally than build a *Default responder at every return. Stick with the default responder style when each handler already knows the exact response it wants.

Related

• Todo list server — the default responder style.
• Strict server — compiler-enforced responders.
• Hand-wiring error handling without codegen? See the go-openapi/runtime examples.

Auto-configure

Normally you edit configure_*.go by hand to attach each handler. The auto-configure example takes a different route: generate with --implementation-package, point it at a package you write, and the generator emits the wiring for you. Every operation is routed to a method on your implementation — no hand-editing of a configure file.

The generated contract

Instead of a configure_*.go, the generator produces auto_configure_*.go. It declares the Handler interface your package must satisfy, and binds a package-level Impl to your constructor via implementation.New():

var Impl Handler = implementation.New()

// Handler handles all api server backend configurations and requests
type Handler interface {
	Authable
	Configurable
	TodosHandler
}

// Configurable handles all server configurations
type Configurable interface {
	ConfigureFlags(api *operations.AToDoListApplicationAPI)
	ConfigureTLS(tlsConfig *tls.Config)
	ConfigureServer(s *http.Server, scheme, addr string)
	CustomConfigure(api *operations.AToDoListApplicationAPI)
	SetupMiddlewares(handler http.Handler) http.Handler
	SetupGlobalMiddleware(handler http.Handler) http.Handler
}

// Authable handles server authentication
type Authable interface {
	// Applies when the "x-todolist-token" header is set
	KeyAuth(token string) (any, error)
}

// TodosHandler
type TodosHandler interface {
	AddOne(params todos.AddOneParams, principal any) middleware.Responder
	DestroyOne(params todos.DestroyOneParams, principal any) middleware.Responder
	FindTodos(params todos.FindTodosParams, principal any) middleware.Responder
	UpdateOne(params todos.UpdateOneParams, principal any) middleware.Responder
}

Full source: auto-configure/restapi/auto_configure_a_to_do_list_application.go

Each generated handler then simply delegates to that Impl:

	api.TodosAddOneHandler = todos.AddOneHandlerFunc(func(params todos.AddOneParams, principal any) middleware.Responder {

		return Impl.AddOne(params, principal)
	})

Full source: auto-configure/restapi/auto_configure_a_to_do_list_application.go

Your implementation package

You write a package that implements Handler. This is ordinary hand-written code — nothing generated — so it’s the natural home for your business logic. Here’s the AddOne method backing the in-memory store:

func (i *TodosHandlerImpl) AddOne(params todos.AddOneParams, principal any) middleware.Responder {
	_ = principal

	i.lock.Lock()
	defer i.lock.Unlock()
	newItem := params.Body
	if newItem == nil {
		return todos.NewAddOneDefault(http.StatusBadRequest).
			WithPayload(&models.Error{
				Code:    http.StatusBadRequest,
				Message: &[]string{"Item Body is nil"}[0],
			})
	}
	// assign new id
	newItem.ID = i.idx
	i.idx++

	i.items[newItem.ID] = newItem
	return todos.NewAddOneCreated().WithPayload(newItem)
}

Full source: auto-configure/implementation/todos_impl.go

The example splits the interface across small types — TodosHandlerImpl, ConfigureImpl, AuthImpl — composed by a single HandlerImpl that New() returns. That keeps handlers, server configuration, and authentication in separate files while still satisfying the one generated Handler interface.

When to use it

Auto-configure shines when you regenerate often and don’t want a hand-edited configure_*.go in the loop: your implementation lives entirely in a package you own, and regeneration only ever touches the generated wiring. It’s also a clean way to keep the transport-facing glue separate from your domain code.

Related

• Todo list server — the conventional hand-wired configure_*.go.
• Custom error handling — centralized error responses.

File server

The file-server example demonstrates a file-upload endpoint: how the spec’s type: file maps onto the generated server and client, and how the runtime surfaces the uploaded file to your handler.

The spec

An upload is a multipart/form-data operation with a formData parameter of type: file:

/upload:
  post:
    tags:
    - uploads
    summary: uploads
    operationId: uploadFile
    consumes:
    - multipart/form-data
    parameters:
    - name: file
      in: formData
      type: file
      required: true

Full source: file-server/swagger.yml

Server side

The generated handler receives the file as an io.ReadCloser on params.File. At runtime it’s a *runtime.File, so a type assertion gives you the multipart header — filename and size — before you stream the body to disk:

api.UploadsUploadFileHandler = uploads.UploadFileHandlerFunc(func(params uploads.UploadFileParams) middleware.Responder {
	if params.File == nil {
		return middleware.Error(http.StatusNotFound, stderrors.New("no file provided"))
	}
	defer func() {
		_ = params.File.Close()
	}()

	if namedFile, ok := params.File.(*runtime.File); ok {
		log.Printf("received file name: %s", namedFile.Header.Filename)
		log.Printf("received file size: %d", namedFile.Header.Size)
	}

	// uploads file and save it locally
	filename := path.Join(uploadFolder, fmt.Sprintf("uploaded_file_%d.dat", uploadCounter))
	uploadCounter++
	f, err := os.OpenFile(filename, os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0o600)
	if err != nil {
		return middleware.Error(http.StatusInternalServerError, stderrors.New("could not create file on server"))
	}

	n, err := io.Copy(f, params.File)
	if err != nil {
		return middleware.Error(http.StatusInternalServerError, stderrors.New("could not upload file on server"))
	}

	log.Printf("copied bytes %d", n)

	log.Printf("file uploaded copied as %s", filename)

	return uploads.NewUploadFileOK()
})

Full source: file-server/restapi/configure_file_upload.go

Note the defer params.File.Close() and the io.Copy into a fresh file — the handler owns the stream and is responsible for draining and closing it.

Client side

On the client, a file argument is a runtime.NamedReadCloser — an io.ReadCloser that also reports a Name(). A plain *os.File satisfies it, so you open the file and pass it straight to the generated parameter builder:

func upload(reader runtime.NamedReadCloser) error {
	config := client.DefaultTransportConfig().WithHost("localhost:8000")

	uploader := client.NewHTTPClientWithConfig(nil, config)

	params := uploads.NewUploadFileParams().WithFile(reader)

	_, err := uploader.Uploads.UploadFile(params)

	return err
}

Full source: file-server/upload_file.go

The generated UploadFile client method handles the multipart encoding; you only supply the reader.

Related

• Streaming request/response bodies instead of a one-shot upload? See Streaming.
• Hand-wiring multipart without codegen? See the go-openapi/runtime examples.

Task tracker

The task-tracker example is a larger, realistic CRUD API — an issue tracker with tasks, comments and file attachments. Its spec is the one go-swagger uses to exercise code generation, so it deliberately packs in almost every construct: nested resources, composition, arrays, file uploads, and multiple security schemes. It’s the best example to see what the generator produces for a non-trivial contract.

The API surface

The spec defines a full CRUD surface across three nested resources:

Each becomes a typed handler on the generated API, with parameters (path, query, body, multipart) bound and validated for you.

Model composition

The spec builds Task on top of a shared TaskCard, and the generator preserves that with Go embedding — plus read-only fields, maps of attachments, and slices of related models:

type Task struct {
	TaskCard

	// The attached files.
	//
	// An issue can have at most 20 files attached to it.
	//
	Attachments map[string]TaskAttachmentsAnon `json:"attachments,omitempty"`

	// The 5 most recent items for this issue.
	//
	// The detail view of an issue includes the 5 most recent comments.
	// This field is read only, comments are added through a separate process.
	//
	// Read Only: true
	Comments []*Comment `json:"comments"`

	// The time at which this issue was last updated.
	//
	// This field is read only so it's only sent as part of the response.
	//
	// Read Only: true
	// Format: date-time
	LastUpdated strfmt.DateTime `json:"lastUpdated,omitempty"`

	// last updated by
	LastUpdatedBy *UserCard `json:"lastUpdatedBy,omitempty"`

	// reported by
	ReportedBy *UserCard `json:"reportedBy,omitempty"`
}

Full source: task-tracker/models/task.go

Read-only fields (Comments, LastUpdated) are populated by the server on responses and ignored on input, exactly as the spec declares.

Two API-key schemes

The spec declares two apiKey security definitions — one carried as a query parameter, one as a header:

api_key:
  type: apiKey
  name: token
  in: query
token_header:
  type: apiKey
  name: X-Token
  in: header

Full source: task-tracker/swagger.yml

The generator turns each into an authenticator hook you implement. The scaffold leaves them returning NotImplemented; you fill in the token validation:

// Applies when the "token" query is set
if api.APIKeyAuth == nil {
	api.APIKeyAuth = func(token string) (any, error) {
		_ = token

		return nil, errors.NotImplemented("api key auth (api_key) token from query param [token] has not yet been implemented")
	}
}
// Applies when the "X-Token" header is set
if api.TokenHeaderAuth == nil {
	api.TokenHeaderAuth = func(token string) (any, error) {
		_ = token

		return nil, errors.NotImplemented("api key auth (token_header) X-Token from header param [X-Token] has not yet been implemented")
	}
}

Full source: task-tracker/restapi/configure_task_tracker.go

For worked authentication examples (basic, api-key, composed, OAuth2), see the Authentication guides.

Related

• Todo list server — the minimal CRUD server to start from.
• File server — the type: file upload mechanics used by /tasks/{id}/files.
• Petstore — another full spec, generated end to end.

Petstore

The Swagger Petstore is the canonical OpenAPI 2.0 sample. The generated/ example is that spec run through swagger generate server — a complete server scaffold for a multi-resource API, useful as a reference for what a “full” spec produces.

Three resource groups

The petstore spec organizes operations under three tags, each becoming its own package of generated handlers:

• pet — addPet, updatePet, findPetsByStatus, findPetsByTags, getPetById, deletePet, uploadFile
• store — getInventory, placeOrder, getOrderById, deleteOrder
• user — createUser, getUserByName, loginUser, logoutUser, …

A generated model

The Pet model shows the usual spec-to-Go mapping — required fields as pointers, nested models by reference, arrays as slices — alongside a generated Validate method (not shown) that enforces the spec’s constraints:

type Pet struct {

	// category
	Category *Category `json:"category,omitempty"`

	// id
	ID int64 `json:"id,omitempty"`

	// name
	// Example: doggie
	// Required: true
	Name *string `json:"name"`

	// photo urls
	// Required: true
	PhotoUrls []string `json:"photoUrls"`

	// pet status in the store
	Status string `json:"status,omitempty"`

	// tags
	Tags []*Tag `json:"tags"`
}

Full source: generated/models/pet.go

Two security schemes

Petstore mixes an api-key header with an OAuth2 flow. The generator emits a distinct authenticator hook for each — note the OAuth2 hook receives the required scopes so you can authorize per operation:

// Applies when the "api_key" header is set
if api.APIKeyAuth == nil {
	api.APIKeyAuth = func(token string) (any, error) {
		_ = token

		return nil, errors.NotImplemented("api key auth (api_key) api_key from header param [api_key] has not yet been implemented")
	}
}
if api.PetstoreAuthAuth == nil {
	api.PetstoreAuthAuth = func(token string, scopes []string) (any, error) {
		_ = token
		_ = scopes

		return nil, errors.NotImplemented("oauth2 bearer auth (petstore_auth) has not yet been implemented")
	}
}

Full source: generated/restapi/configure_petstore.go

See the OAuth2 guide for a fully implemented flow.

Typed vs untyped

This repo also ships the same petstore API hand-wired without codegen, using the go-openapi runtime directly, under 2.0/petstore. That untyped style — building the API from runtime primitives rather than generated code — is the subject of the go-openapi/runtime site. Compare the two to see exactly what swagger generate buys you.

Related

• Todo list server — a smaller server to start from.
• Task tracker — another full spec, generated end to end.

Generated client SDK

From the same spec that drives a server, swagger generate client produces a typed Go SDK: one method per operation, with generated parameter and response types. The tutorials/client example generates that SDK in two flavors from one spec — the classic go-swagger client and the stratoscale contributed template — so you can compare the ergonomics.

Classic client

The classic client generates a ClientService interface. Each method takes the operation’s params plus an explicit runtime.ClientAuthInfoWriter and variadic ClientOptions; a parallel …Context variant threads a context.Context:

	AddOne(params *AddOneParams, authInfo runtime.ClientAuthInfoWriter, opts ...ClientOption) (*AddOneCreated, *AddOneNoContent, error)

	AddOneContext(ctx context.Context, params *AddOneParams, authInfo runtime.ClientAuthInfoWriter, opts ...ClientOption) (*AddOneCreated, *AddOneNoContent, error)

Full source: tutorials/client/classic_client/todos/todos_client.go

Stratoscale client

The stratoscale template generates a leaner API interface: context-first, auth folded into the transport, no options parameter. It also emits a //go:generate mockery directive so the interface is trivially mockable in tests:

	// AddOne add one API
	AddOne(ctx context.Context, params *AddOneParams) (*AddOneCreated, *AddOneNoContent, error)

Full source: tutorials/client/stratoscale_client/todos/todos_client.go

Pick classic for the full go-swagger surface (per-call auth, per-call options); pick stratoscale for a compact, context-first, easily-mocked client.

Multiple success responses

This example deliberately exercises a tricky spec shape: addOne declares two success responses (201 Created and 204 No Content). Both flavors reflect that in the return signature — the method hands back a pointer for each possible success, and exactly one is non-nil:

created, noContent, err := c.AddOne(ctx, params)
switch {
case err != nil:
    // transport or error response
case created != nil:
    // 201 — use created.Payload
case noContent != nil:
    // 204 — nothing to read
}

The same mechanism covers operations with no default response: without a default, an undeclared status code surfaces as a generic error rather than a typed payload, because the generated response reader only knows the codes the spec listed.

Related

• CLI client — a cobra command-line tool wrapping a generated client.
• Custom templates — how the stratoscale flavor is produced.
• Hand-wiring a client without codegen? See the go-openapi/runtime examples.

CLI client

swagger generate cli produces a command-line tool that wraps the generated client: it reads flags and arguments, builds the operation parameters, calls the server, and prints the response. It’s built on cobra and viper, with shell-completion support.

Command layout

The generated command tree mirrors the spec:

• the root command holds global flags (--hostname, --scheme, auth tokens);
• each tag becomes a sub-command (an operation group);
• each operationId becomes a sub-command under its tag;
• each path/query parameter becomes a flag; the body becomes a --body JSON flag, with a flag per body field layered on top.

The tag → sub-command mapping is a cobra.Command per group, wiring in one child per operation:

func makeGroupOfOperationsTodosCmd() (*cobra.Command, error) {
	parent := &cobra.Command{
		Use:  "todos",
		Long: ``,
	}

	sub0, err := makeOperationTodosAddOneCmd()
	if err != nil {
		return nil, err
	}
	parent.AddCommand(sub0)

	sub1, err := makeOperationTodosDestroyOneCmd()
	if err != nil {
		return nil, err
	}
	parent.AddCommand(sub1)

	sub2, err := makeOperationTodosFindTodosCmd()
	if err != nil {
		return nil, err
	}
	parent.AddCommand(sub2)

	sub3, err := makeOperationTodosUpdateOneCmd()
	if err != nil {
		return nil, err
	}
	parent.AddCommand(sub3)

	return parent, nil
}

Full source: cli/cli/cli.go

An operation command

Each operationId gets its own command with a RunE that calls the server, plus generated flag registration for its parameters:

func makeOperationTodosAddOneCmd() (*cobra.Command, error) {
	cmd := &cobra.Command{
		Use:   "addOne",
		Short: ``,
		RunE:  runOperationTodosAddOne,
	}

	if err := registerOperationTodosAddOneParamFlags(cmd); err != nil {
		return nil, err
	}

	return cmd, nil
}

Full source: cli/cli/add_one_operation.go

Body parameters are handled two ways at once — a whole-body --body JSON string as a base payload, and a generated flag per field (recursing into sub-definitions) that overrides it. That’s where --item.description comes from:

func registerOperationTodosAddOneBodyParamFlags(cmdPrefix string, cmd *cobra.Command) error {

	var flagBodyName string
	if cmdPrefix == "" {
		flagBodyName = "body"
	} else {
		flagBodyName = fmt.Sprintf("%v.%s", cmdPrefix, "body")
	}

	_ = cmd.PersistentFlags().String(flagBodyName, "", `Optional json string for [body]. `)

	// add flags for body
	if err := registerModelItemFlags(0, "item", cmd); err != nil {
		return err
	}

	return nil
}

Full source: cli/cli/add_one_operation.go

Running it

Drive the auto-configure server with the tool:

$ go run ./cli/cmd/todoctl/main.go --hostname localhost:12345 \
    --x-todolist-token "example token" \
    todos addOne --item.description "hi" --body "{}"
{"description":"hi"}

The path is todoctl → todos (the tag) → addOne (the operationId), with --item.description setting a body field.

Config files and completion

Common flags — hostname, scheme, base_path, auth tokens — can live in a config file instead of the command line, loaded via viper from ~/.config/<app>/config.json (or --config, in JSON/YAML/env form):

{
    "hostname": "localhost:12345",
    "scheme": "http",
    "x-todolist-token": "example token"
}

Shell completions (bash, zsh, fish, PowerShell) come for free from cobra:

$ source <(./todoctl completion bash)

Related

• Generated client SDK — the typed client this CLI wraps.
• dockerctl — a full CLI generated this way for the Docker Engine API.

Basic & API-key auth

This is the starting point for security in a generated server. A securityDefinition in the spec becomes a generated authenticator hook you implement, and — when you generate with a typed principal — every protected handler receives that principal as a typed argument.

Declaring the scheme

The authentication example uses a single API-key scheme, carried in the x-token header, and applies it to every endpoint via a top-level security requirement:

securityDefinitions:
  key:
    type: apiKey
    in: header
    name: x-token
security:
  - key: []

Full source: authentication/swagger.yml

The generated authenticator hook

Because the spec names one apiKey scheme called key, the generated API exposes an api.KeyAuth hook. The --principal models.Principal flag makes it return a typed *models.Principal; the scaffold leaves it returning NotImplemented:

if api.KeyAuth == nil {
	api.KeyAuth = func(token string) (*models.Principal, error) {
		_ = token

		return nil, errors.NotImplemented("api key auth (key) x-token from header param [x-token] has not yet been implemented")
	}
}

Full source: authentication/restapi/configure_auth_sample.go

You replace the body with your token check. On success return a principal; on failure return an errors.New(401, …):

api.KeyAuth = func(token string) (*models.Principal, error) {
    if token == "abcdefuvwxyz" {
        prin := models.Principal(token)
        return &prin, nil
    }
    return nil, errors.New(401, "incorrect api key auth")
}

The returned principal is then passed to every handler protected by this scheme:

api.CustomersGetIDHandler = customers.GetIDHandlerFunc(
    func(params customers.GetIDParams, principal *models.Principal) middleware.Responder {
        // principal is the value your KeyAuth hook returned
        ...
    })

Basic auth is the same shape

A type: basic scheme works identically, except the runtime decodes the Authorization: Basic header for you and the hook receives a username/password pair instead of a single token:

api.MyBasicAuth = func(user, pass string) (*models.Principal, error) { ... }

For a worked basic-auth authenticator — plus mixing several schemes — see Composed auth.

Trying it

$ curl -i -H 'X-Token: abcdefuvwxyz' http://127.0.0.1:35307/api/customers
HTTP/1.1 501 Not Implemented          # authenticated, handler not implemented

$ curl -i -H 'X-Token: wrong' http://127.0.0.1:35307/api/customers
HTTP/1.1 401 Unauthorized
{"code":401,"message":"incorrect api key auth"}

Related

• Composed auth — basic + API-key + scoped tokens, composed with AND/OR.
• OAuth2 access-code — a full OAuth2 handshake.
• Hand-wiring auth without codegen? See the runtime auth examples.

Composed auth

Real APIs rarely have a single security scheme. The composed-auth example mixes four — basic auth, an API key (by header or query), and scoped JWT tokens — and composes them per operation with AND and OR semantics. It’s the reference for anything beyond a single authenticator.

Four schemes

The spec declares basic auth (isRegistered), an API key in either the header (isReseller) or a query param (isResellerQuery), and a scoped oauth2-typed scheme (hasRole) used purely to carry JWT scopes — go-swagger does not run an OAuth2 flow here, it just extracts the required scopes and hands them to your authorizer:

isRegistered:
  # This scheme uses the header: "Authorization: Basic {base64 encoded string defined by username:password}"
  # Scopes are not supported with this type of authorization.
  type: basic
isReseller:
  # This scheme uses the header: "X-Custom-Key: {base64 encoded string}"
  # Scopes are not supported with this type of authorization.
  type: apiKey
  in: header
  name: X-Custom-Key
isResellerQuery:
  # This scheme uses the query parameter "CustomKeyAsQuery"
  # Scopes are not supported with this type of authorization.
  type: apiKey
  in: query
  name: CustomKeyAsQuery
hasRole:
  # This scheme uses the header: "Authorization: Bearer {base64 encoded string representing a JWT}"
  # Alternatively, the query param: "access_token" may be used.
  #
  # In our scenario, we must use the query param version in order to avoid
  # passing several headers with key 'Authorization'
  type: oauth2
  # The flow and URLs in spec are for documentary purpose: go-swagger does not implement OAuth workflows
  flow: accessCode
  authorizationUrl: 'https://dummy.oauth.net/auth'
  tokenUrl: 'https://dumy.oauth.net/token'
  # Required scopes are passed by the runtime to the authorizer
  scopes:
    customer: scope of registered customers
    inventoryManager: scope of resellers acting as inventory managers

Full source: composed-auth/swagger.yml

Composing requirements with AND / OR

A security block on an operation is a list of alternatives (OR), and each alternative is a map of schemes that must all pass (AND). So /order/add accepts a registered customer, or a reseller (by header), or a reseller (by query) — each combined with the right JWT role:

security:
  - isRegistered: []
    hasRole: [ customer ]
  - isReseller: []
    hasRole: [ inventoryManager ]
  - isResellerQuery: []
    hasRole: [ inventoryManager ]

Full source: composed-auth/swagger.yml

An empty security: [] on an operation opts it out entirely (public), overriding the spec’s top-level default.

The authorizers

Each scheme maps to a hook whose signature depends on its type: basic auth gets (user, pass), an API key gets (token), and a scoped scheme gets (token, scopes). The example delegates each to a function in auth/authorizers.go:

api.HasRoleAuth = func(token string, scopes []string) (*models.Principal, error) {
	// The header: Authorization: Bearer {base64 string} (or ?access_token={base 64 string} param) has already
	// been decoded by the runtime as a token
	api.Logger("HasRoleAuth handler called")
	return auth.HasRole(token, scopes)
}
// Applies when the Authorization header is set with the Basic scheme
api.IsRegisteredAuth = func(user string, password string) (*models.Principal, error) {
	// The header: Authorization: Basic {base64 string} has already been decoded by the runtime as a
	// username:password pair
	api.Logger("IsRegisteredAuth handler called")
	return auth.IsRegistered(user, password)
}
// Applies when the "X-Custom-Key" header is set
api.IsResellerAuth = func(token string) (*models.Principal, error) {
	api.Logger("IsResellerAuth handler called")
	return auth.IsReseller(token)
}
// Applies when the "CustomKeyAsQuery" query is set
api.IsResellerQueryAuth = func(token string) (*models.Principal, error) {
	api.Logger("ResellerQueryAuth handler called")
	return auth.IsReseller(token)
}

Full source: composed-auth/restapi/configure_multi_auth_example.go

The basic-auth authorizer is a plain credential check returning a typed principal:

// IsRegistered determines if the user is properly registered,
// i.e if a valid username:password pair has been provided.
func IsRegistered(user, pass string) (*models.Principal, error) {
	password, ok := userDb[user]
	if !ok || pass != password {
		return nil, errors.New(401, "Unauthorized: not a registered user")
	}

	return &models.Principal{
		Name: user,
	}, nil
}

Full source: composed-auth/auth/authorizers.go

The scoped HasRole authorizer goes further: it parses the JWT, then checks the token’s claimed roles against the scopes the runtime passed in — the mechanism that makes hasRole: [ customer ] in the spec actually mean something.

Trying it

Generate test keys and JWTs, then exercise the composed requirements:

$ cd hack/tools && go run . gen-tokens        # RSA keypair + role JWTs
$ ./composed-auth/exerciser.sh                # sends a sequence of curl requests

Related

• Basic & API-key auth — the single-scheme starting point.
• OAuth2 access-code — a real OAuth2 handshake (vs. JWT-scope extraction here).

OAuth2 access-code

The other auth examples validate a token the client already has. This one runs the full OAuth2 access-code handshake — redirecting the user to an identity provider (Google), receiving a callback, exchanging the code for a token, then using that token to authenticate API calls.

The scheme

The spec declares an oauth2 scheme with the accessCode flow and its authorization/token URLs. Unlike composed-auth — which only borrows the oauth2 type to carry scopes — here the URLs are real and drive an actual handshake:

securityDefinitions:
  OauthSecurity:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth'
    tokenUrl: 'https://www.googleapis.com/oauth2/v4/token'
    scopes:
      admin: Admin scope
      user: User scope

Full source: oauth2/swagger.yml

Step 1 — redirect to the provider

The public /login endpoint sends the user to Google’s consent screen, using the golang.org/x/oauth2 config built in implementation.go:

func login(r *http.Request) middleware.Responder {
	// implements the login with a redirection
	return middleware.ResponderFunc(
		func(w http.ResponseWriter, _ runtime.Producer) {
			http.Redirect(w, r, config.AuthCodeURL(state), http.StatusFound)
		})
}

Full source: oauth2/restapi/implementation.go

Step 2 — handle the callback and exchange the code

Google redirects back to /auth/callback with a state and a code. The handler verifies state, then exchanges the code for an access token via the oauth2 client:

func callback(r *http.Request) (string, error) {
	// we expect the redirected client to call us back
	// with 2 query params: state and code.
	// We use directly the Request params here, since we did not
	// bother to document these parameters in the spec.

	if r.URL.Query().Get("state") != state {
		log.Println("state did not match")
		return "", errors.New("state did not match")
	}

	myClient := &http.Client{}

	parentContext := context.Background()
	ctx := oidc.ClientContext(parentContext, myClient)

	authCode := r.URL.Query().Get("code")
	log.Printf("Authorization code: %v\n", authCode)

	// Exchange converts an authorization code into a token.
	// Under the hood, the oauth2 client POST a request to do so
	// at tokenURL, then redirects...
	oauth2Token, err := config.Exchange(ctx, authCode)
	if err != nil {
		log.Println("failed to exchange token", err.Error())
		return "", errors.New("failed to exchange token")
	}

	// the authorization server's returned token
	log.Println("Raw token data:", oauth2Token)
	return oauth2Token.AccessToken, nil
}

Full source: oauth2/restapi/implementation.go

Step 3 — authenticate API calls with the token

Every protected endpoint runs through the generated OauthSecurityAuth hook. It validates the bearer token (here by calling Google’s userinfo endpoint) and returns the principal — the token string itself in this minimal example:

api.OauthSecurityAuth = func(token string, scopes []string) (*models.Principal, error) {
	_ = scopes

	ok, err := authenticated(token)
	if err != nil {
		return nil, errors.New(401, "error authenticate")
	}
	if !ok {
		return nil, errors.New(401, "invalid token")
	}
	prin := models.Principal(token)

	return &prin, nil
}

Full source: oauth2/restapi/configure_oauth_sample.go

Setup

Register an OAuth client at the Google credentials console, set the callback URL to http://127.0.0.1:12345/api/auth/callback, and put the resulting client ID/secret into the var block of implementation.go. Then:

$ go run ./oauth2/cmd/oauth-sample-server/main.go --port 12345
# open http://127.0.0.1:12345/api/login in a browser, log in, copy the token
$ curl -i -H 'Authorization: Bearer <TOKEN>' http://127.0.0.1:12345/api/customers

Related

• Basic & API-key auth — validating a pre-shared credential.
• Composed auth — mixing schemes and extracting JWT scopes.

Streaming server

Swagger 2.0 has no first-class notion of a streaming response, but you can still generate a server that streams. The stream-server example is a countdown API: GET /elapse/{length} emits one newline-delimited JSON object per second until it reaches zero.

Declaring a streaming response

The trick is the response schema: type: string, format: binary. That’s the closest Swagger 2.0 gets to “this endpoint streams bytes”, and it makes the generator produce a response the handler writes to directly rather than a typed payload it serializes for you:

responses:
  200:
    description: Secondly update on remaining time
    # This is the best representation there is in Swagger 2.0 to
    # say that this endpoint has a streaming response.
    # In this implementation, it will be newline delimited JSON
    # bodies, of the `Mark` type defined below
    schema:
      type: string
      format: binary
  403:
    description: Contrived - thrown when length of 11 is chosen

Full source: stream-server/swagger.yml

Writing the stream from the handler

Instead of returning a generated responder, the handler returns a middleware.ResponderFunc — a closure with raw access to the http.ResponseWriter. It grabs the http.Flusher and writes through a small wrapper so each write is pushed to the client immediately:

api.ElapseHandler = operations.ElapseHandlerFunc(func(params operations.ElapseParams) middleware.Responder {
	if params.Length == 11 {
		return operations.NewElapseForbidden()
	}

	return middleware.ResponderFunc(func(rw http.ResponseWriter, _ runtime.Producer) {
		f, _ := rw.(http.Flusher)
		rw.WriteHeader(http.StatusOK)
		_ = myCounter.Down(params.Length, &flushWriter{f: f, w: rw})
	})
})

Full source: stream-server/restapi/configure_countdown.go

The flushWriter is what turns a normal write into a streamed chunk — it flushes after every write, so the client sees each line as it’s produced rather than at the end:

// Via https://play.golang.org/p/PpbPyXbtEs
type flushWriter struct {
	f http.Flusher
	w io.Writer
}

// Via https://play.golang.org/p/PpbPyXbtEs
func (fw *flushWriter) Write(p []byte) (n int, err error) {
	n, err = fw.w.Write(p)
	if fw.f != nil {
		fw.f.Flush()
	}
	return
}

Full source: stream-server/restapi/configure_countdown.go

Producing the chunks

The business logic just encodes one Mark per iteration into the writer, with a one-second pause between them. Because the writer flushes on every Encode, each {"remains":N} line reaches the client in real time:

// Down is the concrete implementation that spits out the JSON bodies.
func (mc *MyCounter) Down(maximum int64, w io.Writer) error {
	if maximum == 11 {
		return errors.New("we don't *do* elevensies")
	}
	e := json.NewEncoder(w)
	for ix := int64(0); ix <= maximum; ix++ {
		r := maximum - ix
		fmt.Printf("Iteration %d\n", r)
		if err := e.Encode(models.Mark{Remains: &r}); err != nil {
			return err
		}

		if ix != maximum {
			time.Sleep(1 * time.Second)
		}
	}

	return nil
}

Full source: stream-server/biz/count.go

Trying it

$ go run ./stream-server/cmd/countdown-server --port=8000
$ curl -N http://127.0.0.1:8000/elapse/5
{"remains":5}
{"remains":4}
{"remains":3}
{"remains":2}
{"remains":1}
{"remains":0}

The response uses Transfer-Encoding: chunked; each line arrives a second apart. A length of 11 returns 403 (a contrived error to show non-streaming responses still work normally).

Related

• Streaming client — consuming this stream from a generated client.
• Hand-wiring a streaming server without codegen? See the go-openapi/runtime examples.

Streaming client

A generated client normally reads the entire response body and unmarshals it into a typed payload. To consume a stream you override that behavior — swap the consumer, and either buffer the whole thing or read it chunk-by-chunk. Two examples show both approaches.

Why the default doesn’t stream

The generated client hands the response body to a consumer, which does an io.Copy into the destination you pass. With the default JSONConsumer that copy blocks until the body is complete and then unmarshals — exactly what you don’t want for a stream. The fix is to install a ByteStreamConsumer for the response mime, so the bytes flow through untouched.

Non-blocking: consume chunks as they arrive

Override the consumer, then pass an io.Pipe writer as the destination. The client’s io.Copy writes into the pipe while a goroutine reads the other end — so bytes are processed the moment they arrive:

customized := httptransport.New("localhost:8000", "/", []string{"http"})
customized.Consumers[runtime.JSONMime] = runtime.ByteStreamConsumer()

countdowns := client.New(customized, nil)

reader, writer := io.Pipe()

scanner := bufio.NewScanner(reader)

Full source: stream-server/elapsed_client.go

A bufio.Scanner on the read end splits the stream on newlines and unmarshals each line independently. cancel() (via defer) tears down the request if the reader stops early:

wg.Add(1)
go func(wg *sync.WaitGroup) {
	defer wg.Done()
	defer cancel()

	// read response items line by line
	for scanner.Scan() {
		// each response item is JSON
		txt := scanner.Text()
		log.Printf("received countdown mark - raw: %s", txt)

		var mark models.Mark

		err := json.Unmarshal([]byte(txt), &mark)
		if err != nil {
			log.Printf("unmarshal error: %v", err)
			return
		}

		log.Printf("received countdown mark - remaining: %d", conv.Value(mark.Remains))
	}

	if err := scanner.Err(); err != nil {
		log.Printf("scanner err: %v", err)
	}

	log.Println("EOF")
}(&wg)

Full source: stream-server/elapsed_client.go

The request runs on the main goroutine, writing into the pipe the scanner drains; a context timeout bounds how long it will keep the connection open:

elapsed := operations.NewElapseParamsWithContext(queryCtx).WithLength(n)

_, err := countdowns.Operations.Elapse(elapsed, writer)

Full source: stream-server/elapsed_client.go

Blocking: buffer the whole stream

If you don’t need incremental processing, the simplest path is a destination that knows how to accept text/plain. Give a buffer an UnmarshalText method and the default consumer will fill it:

// Buffer knows how to UnmarshalText
type Buffer struct {
	*bytes.Buffer
}

// UnmarshalText handles text/plain
func (b *Buffer) UnmarshalText(text []byte) error {
	_, err := b.Write(text)
	return err
}

Full source: stream-client/jigsaw.go

Then pass it straight to the operation and read it once the call returns:

func chunkedBlocking(withChunks bool) error {
	c := client.New(customTransport(withChunks), nil).Operations

	// we just need to specify a buffer that knows how to UnmarshalText()
	buf := NewBuffer()
	_, err := c.Chunked(operations.NewChunkedParams(), buf)
	if err != nil {
		return err
	}

	data, err := io.ReadAll(buf)
	if err != nil {
		return err
	}

	log.Printf("result: %v", string(data))
	return nil
}

Full source: stream-client/jigsaw.go

The jigsaw.go example also has a non-blocking variant that installs transport.Consumers[runtime.TextMime] = runtime.ByteStreamConsumer() — the same technique as above, for a text/plain stream instead of newline-delimited JSON.

Choosing an approach

• Blocking + UnmarshalText — least code; fine when you can wait for the full response.
• Non-blocking + ByteStreamConsumer + io.Pipe — process items as they arrive, cancel early, bound with a context. Use this for long-lived or unbounded streams.

Related

• Streaming server — the countdown server elapsed_client.go consumes.

Custom templates

go-swagger renders code from Go templates, and you can swap in your own. The contributed-templates example uses the built-in --template stratoscale option — a community template set that produces a different, interface-first shape optimized for testability.

What the template changes

Instead of the default’s per-operation handler func fields, the stratoscale template groups operations into interfaces — one per tag — that your code implements, and emits //go:generate mockery directives so those interfaces are trivially mockable in tests:

//go:generate mockery --name PetAPI --inpackage

// PetAPI
type PetAPI interface {
	// PetCreate Add a new pet to the store
	PetCreate(ctx context.Context, params pet.PetCreateParams) middleware.Responder
	// PetDelete Deletes a pet
	PetDelete(ctx context.Context, params pet.PetDeleteParams) middleware.Responder
	// PetGet Get pet by it's ID
	PetGet(ctx context.Context, params pet.PetGetParams) middleware.Responder
	// PetList List pets
	PetList(ctx context.Context, params pet.PetListParams) middleware.Responder
	// PetUpdate Update an existing pet
	PetUpdate(ctx context.Context, params pet.PetUpdateParams) middleware.Responder
	// PetUploadImage uploads an image
	PetUploadImage(ctx context.Context, params pet.PetUploadImageParams) middleware.Responder
}

Full source: contributed-templates/stratoscale/restapi/configure_petstore.go

Every handler is context-first (ctx context.Context, params …), matching the stratoscale client flavor. You provide one implementation per interface (PetAPI, StoreAPI, …) rather than assigning individual handler funcs.

When to use it

Reach for a custom template set when the default output doesn’t fit your codebase conventions — here, interface-based handlers plus generated mocks. Because it’s a whole template family, it changes server and client output consistently.

To go further, --template-dir points the generator at your own template directory, letting you override any individual template go-swagger ships.

Related

• Generated client SDK — the stratoscale client interface, side by side with the classic one.
• Generation flags — other flags that reshape the output.

External types

By default every schema in your spec becomes a generated Go struct. Sometimes you want a schema to map onto a type you already have — a hand-written type, one from another package, or a shared domain type. The external-types example shows how x-go-type binds a schema to an externally defined Go type instead of generating one.

The x-go-type extension

Attach x-go-type to a schema to name the Go type it should use, and where to import it from. Here a property is bound to MyAlternateInteger from the fred package instead of getting a generated type:

gamma:
  description: |
    Property defined as an external type from package "fred"

  x-go-type:
    type: MyAlternateInteger
    import:
      package: "github.com/go-swagger/examples/external-types/fred"

Full source: external-types/example-external-types.yaml

The import.package (and optional alias) tell the generator which import to add. The generated code references your type directly — no definition is emitted for it.

The generated result

A definition bound to an external type collapses to exactly that type, with the external package imported (and its name mangled to avoid collisions). This MyExtCollection is a slice of an external go-ext type:

// MyExtCollection This type demonstrates the import generation with name mangling
//
// swagger:model MyExtCollection
type MyExtCollection []go_ext.MyExtType

Full source: external-types/models/my_ext_collection.go

Because the external type is expected to satisfy the runtime’s Validatable interface, the generated Validate still calls into it per item — so your type participates in validation like any generated model.

What it covers

The example exercises the full range of external-type use cases:

• an external type as its own definition, or nested inside an object/slice/map/tuple;
• types pulled from the default models package or from an arbitrary import path;
• embedding an external type to add the Validatable interface;
• annotation hints to resolve nullable/struct-vs-interface questions and to skip validation of an external type.

Related

• Custom templates — reshape the generated code itself.
• Generation flags — control model/target packages.

Generation flags

The generated main.go for a server isn’t fixed — a couple of flags change how it parses command-line options and whether it carries the spec inside the binary. The flags example generates the same API six ways so you can compare the results side by side.

--flag-strategy — how the server parses CLI options

The flag strategy selects the library the generated main.go uses for its command-line flags. The API is identical; only the flag plumbing differs:

(mkdir pflag && cd pflag && swagger generate server --spec=../swagger.yml --flag-strategy=pflag)

All three expose the same server options — listeners (--scheme), timeouts, TLS settings, socket path — just rendered in each library’s idiom. Pick the one that matches the rest of your CLI.

--exclude-spec — embedded vs. runtime spec

By default the spec is embedded in the generated binary (the x… variants drop this):

• default (embedded) — the spec is baked in; the server is fully self-contained and serves its own swagger.json.
• --exclude-spec — the spec is not embedded. An extra --spec CLI flag appears so the server loads the document at startup instead.

Embed for a single shippable artifact; exclude when you want to swap the spec without rebuilding, or to keep the binary small.

Trying it

Build any variant’s server and ask for help to see that strategy’s flag layout:

$ go build -o srv ./flags/pflag/cmd/simple-to-do-list-api-server && ./srv -h

Related

• Custom templates — change the generated code shape, not just its flags.
• CLI client — a different use of flags: a generated cobra command-line client.

Custom middleware

A generated server is a standard net/http stack, so any http.Handler middleware composes with it. The middleware example wires two real concerns — security response headers and Prometheus metrics — into a generated server using only the hook points codegen already leaves for you. No --exclude-main and no custom router required.

Two extension points

Codegen leaves two hooks in restapi/configure_*.go, and they run at different stages of the request:

The global hook — headers + metrics mount

setupGlobalMiddleware wraps the entire server. Reading outermost to innermost: metrics.Mount intercepts GET /metrics so scrape traffic bypasses routing; unrolled/secure adds HSTS and other headers to every response, including the spec and UI:

// setupGlobalMiddleware wraps everything the server serves, including the
// swagger spec document and the embedded UI.
//
// Order matters. From outermost to innermost:
//
//  1. metrics.Mount intercepts GET /metrics so scrape traffic bypasses the
//     swagger router as well as the headers and instrumentation below.
//  2. unrolled/secure injects HSTS and other security response headers on
//     every response, including /swagger.json and the UI assets.
//  3. The swagger handler itself (which will pass through setupMiddlewares
//     once a route is matched).
func setupGlobalMiddleware(handler http.Handler) http.Handler {
	sec := secure.New(secure.Options{
		STSSeconds:           63072000,
		STSIncludeSubdomains: true,
		// ForceSTSHeader: true emits HSTS even on plain-HTTP requests so the
		// example is easy to exercise with `curl http://...`. In production
		// you would either serve over HTTPS directly (the library detects it
		// from the TLS connection) or set SSLProxyHeaders so detection works
		// behind a TLS-terminating proxy — and leave ForceSTSHeader at false.
		ForceSTSHeader:     true,
		FrameDeny:          true,
		ContentTypeNosniff: true,
		ReferrerPolicy:     "no-referrer",
		// Send "X-XSS-Protection: 0" explicitly. The default BrowserXssFilter
		// option sends "1; mode=block", which is now considered harmful in
		// some browsers; modern OWASP / MDN guidance is to disable the
		// legacy XSS auditor outright. See README.
		CustomBrowserXssValue: "0",
	})

	return metrics.Mount(sec.Handler(handler))
}

Full source: middleware/restapi/configure_greeter.go

The per-route hook — instrumentation

setupMiddlewares runs after routing, so the matched route is available. That’s what lets metrics be labelled by route:

// setupMiddlewares wraps the swagger handler after routing.
//
// At this point, [middleware.MatchedRouteFrom] returns the matched route, so
// this is the right place to plug per-route instrumentation. Requests that do
// not match an operation (404/405) never reach this layer; that is by design
// for an example whose metrics describe API operation behaviour.
func setupMiddlewares(handler http.Handler) http.Handler {
	return metrics.Instrument(handler)
}

Full source: middleware/restapi/configure_greeter.go

The go-swagger-specific glue: the route label

The one piece that’s specific to a go-swagger server is the metrics route label. It uses middleware.MatchedRouteFrom(r).PathPattern — the swagger path template (/greet/{name}) rather than the literal path (/greet/alice) — so Prometheus label cardinality stays bounded instead of exploding one series per distinct URL:

// Instrument records request count and latency for the wrapped handler.
//
// It is meant to be installed in the generated server's setupMiddlewares hook
// (i.e. after swagger routing) so that [middleware.MatchedRouteFrom] returns
// the matched route. The route label is the swagger path template (e.g.
// "/greet/{name}") rather than the literal request path, to keep the metric
// label cardinality bounded.
func Instrument(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		start := time.Now()
		rec := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
		next.ServeHTTP(rec, r)

		route := "unmatched"
		if mr := middleware.MatchedRouteFrom(r); mr != nil && mr.PathPattern != "" {
			route = mr.PathPattern
		}

		obs := prometheus.Labels{
			labelMethod: r.Method,
			labelRoute:  route,
			labelCode:   strconv.Itoa(rec.status),
		}
		requestsTotal.With(obs).Inc()
		requestDuration.With(obs).Observe(time.Since(start).Seconds())
	})
}

Full source: middleware/internal/metrics/metrics.go

Trying it

$ go run ./middleware/cmd/greeter-server --port 8080
$ curl -i http://127.0.0.1:8080/api/greet
HTTP/1.1 200 OK
Strict-Transport-Security: max-age=63072000; includeSubDomains
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
...
{"message":"hello"}

$ curl http://127.0.0.1:8080/metrics
http_requests_total{code="200",method="GET",route="/api/greet/{name}"} 3

The route label carries the basePath (/api) because the matched template is the full path the router serves.

Other middleware, same pattern

Any http.Handler middleware composes identically via setupGlobalMiddleware — panic recovery (gorilla/handlers.RecoveryHandler), a request ID, an access log, and so on. The example keeps to headers + metrics to stay focused on the wiring.

Related

• Todo list server — where the configure_*.go hooks come from.
• Generation flags — --exclude-spec and flag strategies (no --exclude-main needed here).

Alias compatibility

The alias-compatibility example shows how a Go type alias is reflected when you generate a spec from Go code, and how the --transparent-aliases flag controls it.

The aliases

UserID is a true Go alias (=) of Identifier, not a distinct named type:

// Identifier represents a unique identifier.
type Identifier string

// UserID is an alias to Identifier for user-specific IDs.
type UserID = Identifier

Full source: alias-compatibility/api.go

What the flag does

When swagger generate spec walks this code, the alias can be treated two ways:

• Default (post-#3227) — UserID appears as its own definition, and User.id references #/definitions/UserID.
• --transparent-aliases — UserID is not emitted; User.id references #/definitions/Identifier directly (the pre-#3227 behavior).

See the difference by generating both and diffing:

$ swagger generate spec -m -o without-flag.json
$ swagger generate spec -m --transparent-aliases -o with-flag.json
$ diff <(jq . without-flag.json) <(jq . with-flag.json)

Related

• go-openapi/codescan — the code-first (code → spec) workflow this example belongs to.
• External types — the spec-first counterpart: binding a schema to an existing Go type.