Interfaces & layering

All interfaces live in the root package github.com/go-openapi/runtime. Each one comes with a companion *Func adapter so plain functions can be used wherever an implementation is required.

The five interfaces

Consumer — bind a request body to a Go value

type Consumer interface {
    Consume(io.Reader, any) error
}

type ConsumerFunc func(io.Reader, any) error

See the authoritative definition in godoc: runtime.Consumer.

Used on both sides:

• server: deserialize the inbound request body into the parameter struct matched to the operation
• client: deserialize the response body into the operation’s typed result

Producer — write a Go value to an HTTP response

type Producer interface {
    Produce(io.Writer, any) error
}

type ProducerFunc func(io.Writer, any) error

See the authoritative definition in godoc: runtime.Producer.

Used on both sides:

• server: serialize the operation handler’s return value into the response body
• client: serialize a request body before sending

The split between Consumer and Producer is deliberate — request deserialization and response serialization are independent concerns and a given content type may want different behaviour on each side (think of streaming uploads vs. buffered downloads).

Authenticator — turn raw auth data into a principal

type Authenticator interface {
    Authenticate(any) (bool, any, error)
}

type AuthenticatorFunc func(any) (bool, any, error)

See the authoritative definition in godoc: runtime.Authenticator.

The three return values mean:

Server-only. Built-in implementations for Basic, API key, Bearer and OAuth2 live in the security package, each with a context-aware *Ctx variant.

Authorizer — gate the principal for this specific request

type Authorizer interface {
    Authorize(*http.Request, any) error
}

type AuthorizerFunc func(*http.Request, any) error

See the authoritative definition in godoc: runtime.Authorizer.

Authentication answers who; authorization answers may they do this?. Authorizer runs after a principal has been resolved. A non-nil error blocks the request.

Server-only. There is no built-in authorizer — you wire your own.

OperationHandler — your business logic

type OperationHandler interface {
    Handle(any) (any, error)
}

type OperationHandlerFunc func(any) (any, error)

See the authoritative definition in godoc: runtime.OperationHandler.

Server-only. The argument is the bound (and validated) parameter struct; the return value is whatever Producer will then turn into the response body. error propagates to the configured error handler.

Server lifecycle — where each interface fires

For a request that reaches a matched route, the conventional pipeline runs the following stages. Each stage is a separate http.Handler in the chain, composable via middleware.Builder.

flowchart TD
    req(((HTTP request)))
    router["Router<br/>match path/method against spec"]
    sec["Security · Context.Authorize<br/>Authenticator → principal<br/>Authorizer → may proceed?"]
    neg["ContentType / Accept negotiation<br/>pick Consumer + target Producer<br/>(part of BindValidRequest)"]
    bind["Binder<br/>path/query/header/body params<br/>— uses Consumer —"]
    val["Validator<br/>param validation + Validatable"]
    op["OperationExecutor<br/>call OperationHandler.Handle"]
    resp["Responder<br/>— uses Producer —"]
    out(((HTTP response)))

    req --> router --> sec --> neg --> bind --> val --> op --> resp --> out

A few things worth knowing:

• The order above is a convention, not a runtime invariant. It is what the runtime’s untyped path (middleware.newRoutableUntypedAPI) does — it wraps the bind+validate closure with newSecureAPI so that security runs first — and what go-swagger’s generated typed handlers do (each operation’s ServeHTTP calls Context.Authorize then Context.BindValidRequest then the handler). You can compose a different chain via middleware.Builder if you have a reason to.
• Security comes before binding and validation. That way an unauthenticated request short-circuits with 401 without paying for parameter binding or body deserialization.
• Auth is a single call site, not two. Context.Authorize runs the configured authenticators in order and, on success, calls the optional Authorizer. An Authenticator returning (false, nil, nil) means “this scheme does not apply” and the next one is tried; a non-nil error short-circuits with 401.
• The pipeline’s stages are documented in detail under server / pipeline.

Client lifecycle — where each interface fires

flowchart TD
    gen["generated client method<br/>(GetPet, ListUsers, …)"]
    cop["ClientOperation<br/>{Params, Reader, …}<br/>(request descriptor)"]
    submit["Runtime.Submit"]
    enc["Producer<br/>encode body → *http.Request"]
    auth["AuthInfoWriter<br/>attach auth headers"]
    rt["Transport.RoundTrip<br/>(net/http)"]
    dec["Consumer<br/>decode response body"]
    res(((typed result)))

    gen --> cop --> submit
    submit --> enc --> rt
    submit --> auth --> rt
    rt --> dec --> res

Authenticator and Authorizer are not used on the client. Client-side auth is attached through AuthInfoWriter, covered under client / authentication.

Which interface goes where?

Content types

Consumer and Producer (interfaces page) are the seam through which every wire format plugs in.

The runtime ships a handful of built-in factories for the formats most OpenAPI specs use; anything else is a function call away.

Built-in factories

All factories return ready-to-use Consumer / Producer values. They are side-effect free — call them as many times as you like.

YAML lives in a sub-package (github.com/go-openapi/runtime/yamlpc) to keep the YAML dependency optional.

The CSV and bytestream factories accept option functions (e.g. runtime.ClosesStream to make a stream consumer close the underlying reader). See the godoc for the full option list.

Registering codecs on a server

The server side keeps two map[mediaType]Consumer / …Producer lookups, populated at API construction time. For an untyped API:

api := untyped.NewAPI(spec)
api.RegisterConsumer(runtime.JSONMime, runtime.JSONConsumer())
api.RegisterProducer(runtime.JSONMime, runtime.JSONProducer())
api.RegisterConsumer("application/vnd.acme.v1+json", runtime.JSONConsumer())
api.RegisterProducer("application/vnd.acme.v1+json", runtime.JSONProducer())

Full source: docs/examples/core/contenttypes/main.go

Code generated by go-swagger calls these for you, one entry per consumes and produces value declared in the spec.

Registering codecs on a client

client.Runtime exposes per-content-type maps via Consumers and Producers on the runtime value. Generated clients populate them; for direct use:

rt := client.New("api.example.com", "/v1", []string{"https"})
rt.Consumers[runtime.JSONMime] = runtime.JSONConsumer()
rt.Producers[runtime.JSONMime] = runtime.JSONProducer()

Full source: docs/examples/core/contenttypes/main.go

Writing a custom Consumer / Producer

A consumer is a function. The runtime never inspects its concrete type — implementing Consumer (or supplying a ConsumerFunc) is enough.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// SPDX-License-Identifier: Apache-2.0

// Package customcodec illustrates how to implement a runtime.Consumer for a
// custom wire format. Uint32Consumer decodes a single big-endian 32-bit
// unsigned integer from the request body into a *uint32 target.
package customcodec

import (
	"encoding/binary"
	"fmt"
	"io"

	"github.com/go-openapi/runtime"
)

// Uint32Consumer returns a runtime.Consumer that reads a single big-endian
// uint32 from r and stores it at v (which must be a *uint32).
func Uint32Consumer() runtime.Consumer {
	return runtime.ConsumerFunc(func(r io.Reader, v any) error {
		p, ok := v.(*uint32)
		if !ok {
			return fmt.Errorf("uint32 consumer: target %T is not *uint32", v)
		}
		return binary.Read(r, binary.BigEndian, p)
	})
}

Full source: docs/examples/customcodec/uint32.go

Register the resulting Consumer under whatever MIME types should dispatch to it.

Selection rules

How the runtime chooses which consumer / producer to use for a given request — including wildcards, MIME parameters, and the asymmetric matching rule — is documented in tutorials / media-type selection and surfaced site-side under standalone / content negotiation.

Client-side override: ContentTyper

A request body value can declare its own Content-Type by implementing runtime.ContentTyper:

type ContentTyper interface {
    ContentType() string
}

When a body payload set via SetBodyParam is a stream and ContentType() returns a non-empty value, that value wins over the operation’s consumes default. Same goes for individual file values inside a multipart upload. The full algorithm is in tutorials / media-type selection.

Validation hooks

OpenAPI specifies most validation declaratively (required fields, pattern, min/max, enum, etc.). go-swagger turns those rules into code on the generated model types via two interfaces:

type Validatable interface {
    Validate(strfmt.Registry) error
}

type ContextValidatable interface {
    ContextValidate(context.Context, strfmt.Registry) error
}

Both live in the root runtime package — see runtime.Validatable and runtime.ContextValidatable for the authoritative definitions. The strfmt.Registry argument carries the active string-format registry (date-time, UUID, …) so format-aware validation has access to it.

ContextValidatable is the context-aware version; it should be preferred in new code because some validations (read-only / write-only flags, async-driven cross-field checks) genuinely need request scope.

When the runtime calls them

Server-side, validation runs as part of Context.BindValidRequest, which fires after security and just after parameter binding:

flowchart TD
    sec["Security · Context.Authorize<br/>Authenticator → Authorizer"]
    bind["Binder<br/>Consumer decodes body into the parameter struct"]
    val["Validator (per parameter)<br/>1. spec-driven validation (required, pattern, …)<br/>2. if Validatable: Validate(formats)<br/>3. if ContextValidatable: ContextValidate(ctx, formats)"]
    err{{"errors.CompositeValidationError<br/>aggregates every parameter-level violation<br/>(does not stop on first failure)"}}

    sec --> bind --> val
    val -. on error .-> err

Two consequences worth being aware of:

• Multiple errors per parameter set. A request with three invalid fields produces a CompositeValidationError containing three entries, not a single one.
• Both layers run. Implementing Validatable does not turn off spec-driven validation; the two layers compose. Use Validatable for rules the spec cannot express (cross-field invariants, business rules).

Client-side, generated request models implement the same interfaces, and the generated Validate method runs before the body is serialised — a malformed payload fails locally instead of producing a server-side 422.

Custom validation in your own types

Most users never write these by hand — they fall out of swagger generate. But for hand-rolled types you can add cross-field checks like this:

// DateRange illustrates a cross-field invariant on a hand-written type.
type DateRange struct {
	From strfmt.Date `json:"from"`
	To   strfmt.Date `json:"to"`
}

// Validate enforces that To is not before From. The strfmt.Registry
// argument is unused here because the rule does not involve any
// registered string format.
func (d DateRange) Validate(_ strfmt.Registry) error {
	if time.Time(d.To).Before(time.Time(d.From)) {
		return errors.New("DateRange.to must not be before DateRange.from")
	}
	return nil
}

Full source: docs/examples/core/validation/main.go

For checks that depend on the request:

// ContextValidate enforces that on_behalf_of is only set when the
// request context carries an authenticated user.
func (r MyRequest) ContextValidate(ctx context.Context, _ strfmt.Registry) error {
	if reqUser(ctx) == "" && r.OnBehalfOf != "" {
		return errors.New("on_behalf_of is only valid when authenticated")
	}
	return nil
}

Full source: docs/examples/core/validation/main.go

Strfmt registry

Both methods take a strfmt.Registry, which is how the runtime carries named formats (date-time, uuid, email, …) into the validator. You rarely build one by hand — the server’s *Context and the client Runtime each carry one and pass it down. To register a custom format (x-go-type style), call strfmt.Default.Add(...) once at startup; the default registry is what both sides use unless overridden.

Transport

client.Runtime wraps a *http.Client plus the wire-format codecs needed to call an OpenAPI-described API. This page covers the knobs that shape the underlying HTTP behaviour; auth, tracing and request submission live on their own pages.

Constructors

func New(host, basePath string, schemes []string) *Runtime
func NewWithClient(host, basePath string, schemes []string, client *http.Client) *Runtime

See client.New and client.NewWithClient for the authoritative signatures.

New builds a runtime against http.DefaultTransport. NewWithClient takes an explicit *http.Client — use it when you need a non-default transport (custom TLS, a proxy, an instrumented round-tripper, etc.) or want to share a client across runtimes.

schemes lists allowed URL schemes ("https", "http"); the runtime picks one when building a request, preferring HTTPS.

What New sets up for you

You can replace any of these after construction. Example: register a custom codec for a vendor JSON content type that the client will encounter on responses.

rt := client.New("api.example.com", "/v1", []string{"https"})
rt.Consumers["application/vnd.acme.v1+json"] = runtime.JSONConsumer()
rt.Producers["application/vnd.acme.v1+json"] = runtime.JSONProducer()

Full source: docs/examples/client/transport/main.go

TLS — TLSClientAuth and TLSClientOptions

For mutual TLS, custom CAs or certificate pinning, build a *tls.Config via TLSClientAuth:

tlsCfg, err := client.TLSClientAuth(client.TLSClientOptions{
	Certificate: "/etc/ssl/client.pem",
	Key:         "/etc/ssl/client-key.pem",
	CA:          "/etc/ssl/ca.pem",
	ServerName:  "api.internal",
})
if err != nil {
	return nil, err
}

httpClient := &http.Client{
	Transport: &http.Transport{TLSClientConfig: tlsCfg},
}
rt := client.NewWithClient("api.internal", "/v1", []string{"https"}, httpClient)

Full source: docs/examples/client/transport/main.go

Option highlights (the full struct is in the godoc):

TLSClientAuth always returns a config with MinVersion = TLS 1.2.

Timeouts

Two layers of timeout apply:

1. Per-request timeout — set via the operation’s Params.SetTimeout(d) (any generated parameter type implements this). This becomes the deadline of the request context.Context derived inside BuildHTTPContext (see requests).
2. HTTP client timeout — set on the *http.Client you pass to NewWithClient. This is the standard Client.Timeout field; it applies regardless of the per-request value.

There is also a package-level DefaultTimeout = 30 * time.Second. It is not wired up automatically; it exists for callers building their own *http.Client that want to use the same default the runtime advertises.

httpClient := &http.Client{Timeout: client.DefaultTimeout}
rt := client.NewWithClient(host, base, schemes, httpClient)

Full source: docs/examples/client/transport/main.go

Proxy

Proxy configuration lives on the underlying *http.Transport, not on Runtime. Two common patterns:

1. Honour HTTPS_PROXY / HTTP_PROXY (default behaviour anyway):

// Honour HTTPS_PROXY / HTTP_PROXY (default behaviour anyway).
tr := &http.Transport{Proxy: http.ProxyFromEnvironment}

httpClient := &http.Client{Transport: tr}
rt := client.NewWithClient(host, base, schemes, httpClient)

Full source: docs/examples/client/transport/main.go

2. Force a specific proxy:

// Force a specific proxy.
proxyURL, _ := url.Parse("http://proxy.internal:3128")
tr := &http.Transport{Proxy: http.ProxyURL(proxyURL)}

httpClient := &http.Client{Transport: tr}
rt := client.NewWithClient(host, base, schemes, httpClient)

Full source: docs/examples/client/transport/main.go

Keepalive — EnableConnectionReuse

Some servers never close the response body, which prevents Go from reusing the underlying TCP connection. EnableConnectionReuse installs a transport middleware that drains the unread body on Close() so the connection can return to the pool:

rt := client.New("api.example.com", "/v1", []string{"https"})
rt.EnableConnectionReuse()

Full source: docs/examples/client/transport/main.go

This is not enabled by default because for some servers the response stream never completes and draining would block forever. Turn it on when you’ve confirmed the server you’re talking to does the right thing.

Debug logging

Two ways to enable wire-level dumps of requests and responses (both go through httputil.DumpRequest / DumpResponse):

• Set the SWAGGER_DEBUG (or DEBUG) environment variable before the process starts. client.New picks this up.
• Call rt.SetDebug(true) at runtime.

rt.SetLogger(myLogger) swaps the destination away from the default standard-library logger.

For most production debugging you’ll get more value out of the OpenTelemetry tracing than from raw dumps.

Authentication

Client-side authentication is a pure encoding concern: take some credentials, write the right header / query parameter on the outbound request. It is decoupled from the server-side Authenticator / Authorizer interfaces (core / interfaces) — those answer “is this request allowed?”, these answer “how do I sign it?”.

The interface — ClientAuthInfoWriter

package runtime

type ClientAuthInfoWriter interface {
    AuthenticateRequest(ClientRequest, strfmt.Registry) error
}

type ClientAuthInfoWriterFunc func(ClientRequest, strfmt.Registry) error

See runtime.ClientAuthInfoWriter for the authoritative definition. Anything with that signature can be used as auth. The ClientRequest argument exposes SetHeaderParam, SetQueryParam, SetBodyParam — i.e. the same surface generated parameter types use to encode themselves.

Where to attach it

Two places, with predictable precedence:

// 1. Per operation — overrides the runtime default
op.AuthInfo = client.BearerToken(token)

// 2. Per runtime — used when the operation does not set its own
rt.DefaultAuthentication = client.BasicAuth("alice", "s3cret")

Full source: docs/examples/client/auth/main.go

The runtime calls the operation’s AuthInfo if set, otherwise the runtime’s DefaultAuthentication. Either may be nil for unauthenticated endpoints.

Built-in helpers

All four return a ready-to-use ClientAuthInfoWriter.

BasicAuth(user, password) — RFC 7617

rt.DefaultAuthentication = client.BasicAuth("alice", "s3cret")

Full source: docs/examples/client/auth/main.go

Sets Authorization: Basic <base64(user:password)>.

APIKeyAuth(name, in, value) — RFC-undefined but ubiquitous

// As an HTTP header
rt.DefaultAuthentication = client.APIKeyAuth("X-Api-Key", "header", apiKey)

// Or as a query parameter
rt.DefaultAuthentication = client.APIKeyAuth("api_key", "query", apiKey)

Full source: docs/examples/client/auth/main.go

in must be "header" or "query". Anything else returns nil — at which point you’ll silently send the request unauthenticated, so check your spelling.

BearerToken(token) — RFC 6750 OAuth2 access tokens

rt.DefaultAuthentication = client.BearerToken(accessToken)

Full source: docs/examples/client/auth/main.go

Sets Authorization: Bearer <token>. For OAuth2 client flows that need to acquire and refresh the token, build the writer around an oauth2.TokenSource from golang.org/x/oauth2 and re-attach it on every call (or use a custom writer that calls Token()).

Compose(auths…) — combine multiple writers

For APIs that require more than one credential header on the same request — say an API key plus a bearer token — chain them:

rt.DefaultAuthentication = client.Compose(
	client.APIKeyAuth("X-Api-Key", "header", apiKey),
	client.BearerToken(accessToken),
)

Full source: docs/examples/client/auth/main.go

Nil writers in the list are skipped silently. The first non-nil writer that returns an error short-circuits the chain.

PassThroughAuth — explicit “no auth”

A no-op writer. Use it when the operation requires some writer (for instance because it’s defined as security: [[]] in the spec) but no actual credential should be attached.

op.AuthInfo = client.PassThroughAuth

Full source: docs/examples/client/auth/main.go

Writing your own

A common case: an HMAC-signed request that needs to compute the signature over the body. Implement ClientAuthInfoWriter directly:

// HMACSignature returns a ClientAuthInfoWriter that signs the request
// body with the given HMAC-SHA256 key and attaches the signature plus
// key ID as headers.
func HMACSignature(keyID string, key []byte) runtime.ClientAuthInfoWriter {
	return runtime.ClientAuthInfoWriterFunc(func(r runtime.ClientRequest, _ strfmt.Registry) error {
		body := r.GetBody()
		mac := hmac.New(sha256.New, key)
		mac.Write(body)
		sig := hex.EncodeToString(mac.Sum(nil))
		if err := r.SetHeaderParam("X-Sig-Key", keyID); err != nil {
			return err
		}
		return r.SetHeaderParam("X-Sig", sig)
	})
}

Full source: docs/examples/client/auth/main.go

The runtime calls AuthenticateRequest after the operation’s parameters have been bound but before the request is sent — so r.GetBody() returns the encoded body for buffered payloads. For streaming bodies (multipart, raw streams) the runtime arranges a body-copy closure so the signer sees the bytes that will go on the wire; see BuildHTTPContext in client/internal/request for the gory details.

Tracing

client.Runtime ships first-class OpenTelemetry support. There are no extra modules to import beyond the runtime itself (it already depends on go.opentelemetry.io/otel).

Wire it up — WithOpenTelemetry

See client.Runtime.WithOpenTelemetry for the authoritative signature:

func (r *Runtime) WithOpenTelemetry(opts ...OpenTelemetryOpt) runtime.ClientTransport

Returns a runtime.ClientTransport that delegates to the underlying runtime and creates a client span for every request. Use it as the transport you hand to a generated client:

rt := client.New("api.example.com", "/v1", []string{"https"})
traced := rt.WithOpenTelemetry()

api := petclient.New(traced, strfmt.Default)
result, err := api.Operations.GetPet(petclient.NewGetPetParams().WithID(samplePetID))

Full source: docs/examples/client/tracing/main.go

For untyped use you call traced.Submit(op) directly.

A span only appears when one is already active

If the operation’s context does not contain an active span, the transport does not start a root span. This is intentional — telemetry boundaries belong to the application, not to the transport library. Wrap your call site in a span and the client span attaches beneath it.

Options — OpenTelemetryOpt

Example with a custom name and global tags:

traced := rt.WithOpenTelemetry(
	client.WithSpanNameFormatter(func(op *runtime.ClientOperation) string {
		return "petstore." + op.ID
	}),
	client.WithSpanOptions(
		trace.WithAttributes(
			attribute.String("service.name", "petstore-client"),
		),
	),
)

Full source: docs/examples/client/tracing/main.go

Legacy OpenTracing

Runtime.WithOpenTracing exists but is deprecated. It silently returns an OpenTelemetry transport, ignoring opts that are not OpenTelemetryOpt. The OpenTracing project is archived — new code should call WithOpenTelemetry.

If you still need OpenTracing semantics (for example because your collector is OpenTracing-only), import the compatibility add-on:

go get github.com/go-openapi/runtime/client-middleware/opentracing

import (
    "github.com/go-openapi/runtime/client-middleware/opentracing"
    ottrace "github.com/opentracing/opentracing-go"
)

traced := opentracing.WithOpenTracing(rt, ottrace.GlobalTracer())

The compat module lives in its own Go module so the rest of the runtime no longer pulls the OpenTracing dependency.

Building & submitting requests

Runtime exposes a small set of entry points for turning a runtime.ClientOperation into a sent request and a typed result. The public surface has been pivoting from “use the cached context on the operation/runtime” to “pass the context explicitly”. This page covers both shapes and explains which to use when.

The descriptor — ClientOperation

Authoritative definitions live in the runtime package:

package runtime

type ClientOperation struct {
    ID                 string
    Method             string
    PathPattern        string
    ProducesMediaTypes []string
    ConsumesMediaTypes []string
    Schemes            []string
    AuthInfo           ClientAuthInfoWriter
    Params             ClientRequestWriter
    Reader             ClientResponseReader
    Context            context.Context // legacy — see below
    Client             *http.Client    // optional per-call override
}

type ClientTransport interface {
    Submit(*ClientOperation) (any, error)
}

Generated clients build one of these per operation method and call Submit (or, increasingly, SubmitContext). For untyped use you populate the fields by hand.

Entry points

The runtime offers four methods, paired by purpose:

⚠ CreateHttpRequest is deprecated. It does not return the context’s cancel function, so any per-request timeout set via Params.SetTimeout is silently leaked. Use CreateHTTPRequestContext instead.

Submit vs SubmitContext

Submit consults its context in this order:

1. op.Context if non-nil
2. otherwise rt.Context
3. otherwise context.Background()

SubmitContext(ctx, op) ignores those cached values entirely and uses ctx as the parent context. This is the only way to pass a caller-controlled context that can be cancelled, deadlined or trace-instrumented from the call site.

// legacy — cached context, hard to cancel from the call site
result, err := rt.Submit(op)

// preferred — explicit context
ctx, cancel := context.WithTimeout(parent, exampleTimeout)
defer cancel()
result, err = rt.SubmitContext(ctx, op)

Full source: docs/examples/client/requests/main.go

The per-request timeout set via Params.SetTimeout(d) (i.e. runtime.ClientRequestWriter.SetTimeout) is honoured by both forms — it is applied when the request context is derived inside BuildHTTPContext, on top of whatever deadline ctx already carries.

Build-only — CreateHTTPRequestContext

When you need the prepared *http.Request but want to drive http.Client.Do yourself (for retries, custom logging, response-body inspection), use:

req, cancel, err := rt.CreateHTTPRequestContext(ctx, op)
if err != nil {
	return nil, err
}
defer cancel() // MUST run after the response is fully read

resp, err := myClient.Do(req)
// ...

Full source: docs/examples/client/requests/main.go

cancel releases the per-request timeout timer and any other resources held by the derived context. Calling it before the response body is fully drained will cancel the in-flight request — defer it to the end of the read.

On error the returned cancel is a no-op, so deferring it unconditionally is safe.

What happens during a SubmitContext call

flowchart TD
    in(((SubmitContext ctx, op)))
    prep["prepareRequest<br/>resolve scheme + media type<br/>pick AuthInfoWriter (op.AuthInfo or rt.DefaultAuthentication)"]
    build["BuildHTTPContext<br/>WriteToRequest → ctx with timeout<br/>buffered or streaming body<br/>AuthenticateRequest"]
    do["http.Client.Do"]
    decode["resolveConsumer · ReadResponse<br/>decode into typed result"]
    out(((result, err)))
    cancel["cancel()<br/>(deferred)"]

    in --> prep --> build --> do --> decode --> out
    build -.-> cancel

BuildHTTPContext chooses one of two assembly paths:

• buffered body — for URL-encoded forms, producer output, or no body. The body is materialised in memory before AuthenticateRequest runs, so writers like HMAC signers see the final bytes.
• streaming body — for multipart uploads or stream payloads (io.Reader body). The body flows through an io.Pipe. Auth writers receive a body-copy closure so signers can still see the bytes — at the cost of one extra read.

Multipart uploads honour context cancellation

A long-standing rough edge — the multipart upload goroutine ignoring the request context — was fixed in feat(client): honor context cancellation in multipart upload goroutine. Cancelling the context mid-upload now stops the writer goroutine cleanly instead of leaking it for the lifetime of the connection.

Migration from the legacy form

If your codebase calls Submit and stashes contexts on op.Context or rt.Context, the change is usually mechanical:

// before
op.Context = ctx
result, err := rt.Submit(op)

// after
result, err = rt.SubmitContext(ctx, op)

Full source: docs/examples/client/requests/main.go

op.Context and rt.Context are still read by Submit for compatibility with existing callers and generated code that has not yet been regenerated; SubmitContext ignores both. New code (and freshly regenerated clients) should pass the context explicitly.

For CreateHttpRequest callers the move is more important — the deprecated form leaks the per-request timer when Params.SetTimeout is non-zero. Switch to CreateHTTPRequestContext and remember to defer the returned cancel.

Request pipeline

The middleware package wires an analyzed OpenAPI spec into a working http.Handler. Every request goes through the same conventional sequence of stages — covered briefly on core / interfaces, and expanded here with the actual call sites.

The full picture

flowchart TD
    req(((HTTP request)))
    router["Router · NewRouter / Context.RouteInfo<br/>match path/method against the analyzed spec<br/>404 / 405 if no route"]
    sec["Security · Context.Authorize<br/>RouteAuthenticators.Authenticate<br/>then optional Authorizer<br/>401 / 403 on failure"]
    bvr["BindValidRequest"]
    neg["ContentType / Accept negotiation<br/>pick Consumer + target Producer<br/>400 / 415 / 406 on failure"]
    bind["Binder<br/>path / query / header / body params<br/>— uses Consumer —"]
    val["Validator<br/>spec rules + Validatable<br/>422 with CompositeValidationError on failure"]
    op["OperationHandler.Handle<br/>your business logic"]
    resp["Responder · Context.Respond<br/>— uses Producer —"]
    out(((HTTP response)))

    req --> router --> sec --> bvr
    bvr --> neg --> bind --> val
    val --> op --> resp --> out

The middle three stages — negotiation, binding, validation — all live inside the single call Context.BindValidRequest. Splitting them out in the diagram makes the failure modes (400, 415, 406, 422) easier to trace.

The diagram shows the typical sequence — what the runtime’s default untyped wiring does and what go-swagger’s generated typed handlers do. The actual ordering and composition is an implementation detail of the RoutableAPI plugged into the middleware.Context; a custom one can compose the per-route handler differently.

The RoutableAPI seam

The middleware package handles routing, negotiation, validation and the high-level lifecycle helpers (RouteInfo, Authorize, BindValidRequest, Respond). Everything that has to know about your API — the per-operation handler, the registered codecs, the auth schemes — sits behind a single interface:

package middleware

type RoutableAPI interface {
    HandlerFor(method, path string) (http.Handler, bool)
    ServeErrorFor(path string) func(http.ResponseWriter, *http.Request, error)
    ConsumersFor(mediaTypes []string) map[string]runtime.Consumer
    ProducersFor(mediaTypes []string) map[string]runtime.Producer
    AuthenticatorsFor(schemes map[string]spec.SecurityScheme) map[string]runtime.Authenticator
    Authorizer() runtime.Authorizer
    Formats() strfmt.Registry
    DefaultProduces() string
    DefaultConsumes() string
}

The router calls HandlerFor(method, path) once per matched route and serves whatever it gets back. What that handler does is entirely up to the implementation — the RoutableAPI decides how the bind/validate/security/operation/respond steps are composed.

Constructors that take a custom RoutableAPI

// Default — untyped.API wrapped in a routableUntypedAPI.
ctxDefault := middleware.NewContext(spec, api, nil)

// Custom — anything that implements RoutableAPI.
ctxCustom := middleware.NewRoutableContext(spec, myAPI, nil)

// Same, with a pre-analyzed spec to skip re-analysis.
ctxAnalyzed := middleware.NewRoutableContextWithAnalyzedSpec(spec, analyzed, myAPI, nil)

Full source: docs/examples/server/pipeline/main.go

Use NewRoutableContext when you have your own implementation (typically the one go-swagger generates for typed APIs, but any type satisfying the interface works). Reach for NewRoutableContextWithAnalyzedSpec if you have already produced an *analysis.Spec and want to avoid the second analysis pass.

Two implementations the runtime sees in practice

The runtime ships one RoutableAPI implementation — routableUntypedAPI, internal to the middleware package. It wraps untyped.API and is what middleware.Serve / ServeWithBuilder builds for you.

go-swagger generates a second implementation per spec — the *operations.MyAPI type implements every method on RoutableAPI directly, with HandlerFor returning the per-operation ServeHTTP shown below.

The next section walks both.

Two assembly paths

The two RoutableAPI implementations introduced above produce equivalent pipelines, but differ in where the per-route handler is assembled — the untyped one builds it in the runtime via a closure; the typed one is generated source you can read directly.

Untyped — middleware.Serve / ServeWithBuilder

doc, _ := loads.Spec("api.yaml")
api := untyped.NewAPI(doc)
api.RegisterConsumer(runtime.JSONMime, runtime.JSONConsumer())
api.RegisterProducer(runtime.JSONMime, runtime.JSONProducer())
api.RegisterOperation("get", "/pets/{id}", myGetPetHandler)

srv := &http.Server{
	Addr:              ":8080",
	Handler:           middleware.Serve(doc, api),
	ReadHeaderTimeout: readHeaderTimeout,
}
log.Fatal(srv.ListenAndServe())

Full source: docs/examples/server/pipeline/main.go

Internally middleware.newRoutableUntypedAPI builds one http.Handler per route. The bind/validate/handle/respond logic lives in a single closure; if the route declares any security requirement, that closure is wrapped with newSecureAPI so security runs first:

// excerpt from middleware/context.go
var handler http.Handler = http.HandlerFunc(func(w, r) {
    bound, r, validation = context.BindAndValidate(r, route)
    if validation != nil { context.Respond(...); return }
    result, err := oh.Handle(bound)
    // …
})
if len(schemes) > 0 {
    handler = newSecureAPI(context, handler)   // ← wraps with Authorize
}

Typed — generated ServeHTTP per operation

go-swagger generates a small handler per operation that calls the same primitives in the same order, but spelt out explicitly:

// excerpt from a go-swagger generated *operation.ServeHTTP
func (o *GetOrder) ServeHTTP(rw http.ResponseWriter, r *http.Request) {
    route, rCtx, _ := o.Context.RouteInfo(r)
    if rCtx != nil { *r = *rCtx }

    var Params = NewGetOrderParams()
    uprinc, aCtx, err := o.Context.Authorize(r, route)        // ← security
    if err != nil { o.Context.Respond(rw, r, route.Produces, route, err); return }
    // …

    if err := o.Context.BindValidRequest(r, route, &Params); err != nil { // ← bind+validate
        o.Context.Respond(rw, r, route.Produces, route, err)
        return
    }

    res := o.Handler.Handle(Params, principal)                 // ← operation
    o.Context.Respond(rw, r, route.Produces, route, res)       // ← respond
}

Same primitives, same order. Neither shape is enforced by the runtime: a route is just an http.Handler, and you can wrap or replace it. middleware.Builder exists precisely to compose your own chain on top.

Composing extra middleware — Builder

type Builder func(http.Handler) http.Handler

Builder is the standard http.Handler decorator type, aliased so the API reads cleanly. The runtime exposes several entry points that take one:

A typical pattern with the justinas/alice middleware library — log, rate-limit, then hand off to the runtime:

decorate := func(next http.Handler) http.Handler {
	return alice.New(loggingMW, rateLimitMW).Then(next)
}

handler := middleware.ServeWithBuilder(doc, api, decorate)

Full source: docs/examples/server/pipeline/main.go

PassthroughBuilder is the identity decorator if you need a place to start.

Failure modes by stage

For the matching algorithm and the v0.30 parameter-honouring change behind 415/406 outcomes, see standalone / content negotiation and the canonical tutorials / media-type selection.

Reading values out of the request

Each stage stashes its result in the request context so downstream middleware can read it without re-doing the work:

Use these inside extra middleware mounted via Builder.

Parameter binding & validation

The two stages combined as Context.BindValidRequest turn the incoming *http.Request into a populated parameter struct and surface every spec-level violation in a single response.

What gets bound, in what order

BindValidRequest runs four sub-steps. Any non-recoverable error short-circuits before the binder runs; otherwise binder-level errors are aggregated alongside negotiation errors:

1. Content-Type validation — runtime.HasBody(r) early-outs for bodyless requests; otherwise runtime.ContentType(r.Header) parses the header (a malformed value is a 400) and validateContentType matches it against the operation’s consumes (no match ⇒ 415, match ⇒ pick the registered Consumer; missing Consumer ⇒ 500).
2. Response format selection — negotiate.ContentType(r, route.Produces, …) picks the offer that best satisfies Accept; "" ⇒ 406 (errors.InvalidResponseFormat).
3. Parameter binding — for each declared parameter, the binder reads the right place (path / query / header / formData / body), converts the string(s) to the target Go type and applies any default declared in the spec.
4. Per-parameter validation — the spec’s declarative rules (required, pattern, minLength, enum, format, …) plus any Validatable / ContextValidatable your model implements.

All errors collected during binding and validation are returned as one errors.CompositeValidationError. The validator does not stop on first failure — a request with three problems produces three entries, so callers learn about everything in one round-trip.

Where each parameter in: reads from

The binder is reflection-based for the untyped path; generated code uses the same primitives by calling Context.BindValidRequest(r, route, &Params) where &Params is the generated parameter struct.

Validation layers

Two layers compose. They are not alternatives.

1. Spec-driven validation
   ├─ required, pattern, minLength/maxLength
   ├─ minimum/maximum, multipleOf, exclusive bounds
   ├─ enum, format (date-time, uuid, email, …)
   └─ items / minItems / maxItems / uniqueItems

2. Validatable / ContextValidatable
   ├─ Validate(strfmt.Registry) error                       (sync)
   └─ ContextValidate(ctx, strfmt.Registry) error           (request-scoped)

See core / validation for the full picture of the hooks; BindValidRequest is the call site.

Where this fits in the pipeline

Conventionally after security and before the operation handler — see pipeline for the diagram and the rationale (failed auth short-circuits with 401 before paying the cost of binding/validation).

Disabling spec-driven parameter validation

If you need to bypass the parameters block entirely (typically for test harnesses or proxy layers that re-validate downstream), Context.SetIgnoreParameters(true) skips spec-driven parameter validation while leaving the rest of the pipeline intact:

ctx := middleware.NewContext(spec, api, nil).SetIgnoreParameters(true)
handler := ctx.APIHandler(middleware.PassthroughBuilder)

Full source: docs/examples/server/binding/main.go

Validatable / ContextValidatable hooks on the model still run.

Reading the bound parameters from extra middleware

Bound parameters are cached in the request context. From middleware mounted via Builder you can re-fetch them without re-binding:

// inside middleware.Builder
match := middleware.MatchedRouteFrom(r)
// (no public accessor for the bound struct itself today —
// re-call BindValidRequest if you need it; the result is cached
// so a second call is cheap)

Full source: docs/examples/server/binding/main.go

MatchedRouteFrom plus SecurityPrincipalFrom and SecurityScopesFrom cover the most common middleware needs (audit logging, per-tenant rate limiting, …).

Security schemes

security ships ready-made runtime.Authenticator implementations for the four auth flavours OpenAPI 2.0 understands. Each comes in two shapes — a plain variant and a *Ctx variant that threads context.Context through to your authenticate function.

The user-supplied callback

You don’t implement Authenticator directly — you implement a verification callback and pass it to one of the constructors below. The runtime handles the wire-format details (header parsing, scheme selection, scope handling, etc.).

A successful callback returns the authenticated principal — typed however your application likes. The principal is then handed to any configured Authorizer and stashed in the request context (read with middleware.SecurityPrincipalFrom).

Why *Ctx?

Most real authenticators want request scope: a request-scoped database handle, a tracing span, or a deadline that should propagate into the auth lookup. The *Ctx constructors give your callback the request context and let it return a (possibly enriched) context that the runtime then attaches to the request.

authn := security.BasicAuthCtx(func(ctx context.Context, user, pass string) (context.Context, any, error) {
	// request-scoped DB call honours ctx cancellation
	principal, err := store.AuthenticateBasic(ctx, user, pass)
	if err != nil {
		return ctx, nil, err
	}
	// enrich the context for downstream handlers
	ctx = audit.WithUser(ctx, principal.ID)
	return ctx, principal, nil
})

Full source: docs/examples/server/security/main.go

The non-*Ctx variants exist for compatibility with code from before context propagation was the norm. New code should default to *Ctx.

BasicAuth — RFC 7617

// principal type is up to you
type Principal struct {
	ID    string
	Email string
}

authn := security.BasicAuth(func(user, _ string) (any, error) {
	if user == "" {
		return nil, errors.Unauthenticated("basic")
	}
	return Principal{ID: user, Email: user + "@example.com"}, nil
})

Full source: docs/examples/server/security/main.go

BasicAuth reads r.BasicAuth() and calls your callback with the decoded credentials. Use BasicAuthRealm("my-realm", fn) to set the challenge realm advertised in WWW-Authenticate on failure (default: "Basic Realm").

When the request has no Authorization header, the authenticator returns (false, nil, nil) — “scheme does not apply” — so the next configured scheme is tried. A non-nil error from your callback is treated as a 401.

security.FailedBasicAuth(r) / FailedBasicAuthCtx(ctx) returns the realm name when basic auth has been attempted and failed. Useful from custom error handlers that want to render a WWW-Authenticate challenge.

APIKeyAuth — header or query

authn := security.APIKeyAuth("X-Api-Key", "header",
	func(token string) (any, error) {
		return store.AuthenticateAPIKey(token)
	},
)

Full source: docs/examples/server/security/main.go

in must be "header" or "query" — anything else panics at construction time (it is a programmer error). The callback receives the raw token; an empty value short-circuits with (false, nil, nil) so other schemes can apply.

BearerAuth — OAuth2 / Bearer tokens

authn := security.BearerAuth("oauth2",
	func(token string, requiredScopes []string) (any, error) {
		principal, ok := tokens.Verify(token)
		if !ok {
			return nil, errors.Unauthenticated("bearer")
		}
		if !principal.HasScopes(requiredScopes) {
			return nil, errors.New(http.StatusForbidden, "insufficient_scope")
		}
		return principal, nil
	},
)

Full source: docs/examples/server/security/main.go

The runtime extracts the token from, in order:

1. Authorization: Bearer <token>
2. The access_token query parameter
3. The access_token form field if Content-Type is application/x-www-form-urlencoded or multipart/form-data

That covers RFC 6750 §2.

requiredScopes is whatever the operation declared in its security: block. Combine multiple security entries (per the spec) and you’ll see the union or intersection per call — RouteAuthenticator.AllScopes() and CommonScopes() expose those if you need to inspect them yourself.

The “scheme name” you pass ("oauth2" here) is recoverable from the request via security.OAuth2SchemeName(r) / security.OAuth2SchemeNameCtx(ctx). That’s the hook point for code that needs to know which OAuth2 entry was applied (handy when a spec declares multiple OAuth2 flows).

Authorizer

Authentication says who; authorization says may they do this?. Authorizer runs after a principal has been resolved.

type Authorizer interface {
    Authorize(*http.Request, any) error
}

(see runtime.Authorizer)

The package ships one trivial implementation:

api.RegisterAuthorizer(security.Authorized()) // always allow

Full source: docs/examples/server/security/main.go

Anything more interesting (RBAC, ABAC, OPA / casbin / your own…) you write yourself. A non-nil return blocks the request:

• A return value implementing errors.Error is propagated as-is.
• Any other error is wrapped as errors.New(403, err.Error()).

The single Authorize call on Context (core / interfaces) runs Authenticator and Authorizer in sequence — Authorizer only runs if the authenticator returned a principal.

Composing schemes — RouteAuthenticators

A spec can declare multiple security requirements per operation. The runtime turns each one into a RouteAuthenticator and groups them into RouteAuthenticators. RouteAuthenticators.Authenticate walks the list and:

• returns the first one that returned (true, principal, nil);
• collects errors from any that applied but failed (last one wins for the response status);
• returns AllowsAnonymous() == true if no scheme was required — in that case the request proceeds without a principal.

You don’t construct RouteAuthenticators directly — the runtime builds them from your registered Authenticators (typed APIs do this in generated code; untyped APIs via untyped.API.AddAuth and related). The grouping and short-circuit semantics are worth knowing about when you wonder why “scheme A is rejecting and scheme B never runs”: that’s by design — the first applicable scheme decides.

Reading the principal back

Inside your operation handler, the typed signature gives you the principal directly. From extra middleware mounted via Builder:

principal := middleware.SecurityPrincipalFrom(r)
scopes := middleware.SecurityScopesFrom(r)

Full source: docs/examples/server/security/main.go

scopes is the AllScopes() of the matching RouteAuthenticator — useful for audit logging that needs to record which token (or token shape) authorised the request.

Deprecated shims

In v0.30 the server-side helpers that don’t actually need any OpenAPI machinery were extracted into the server-middleware module. The old entry points in middleware still compile (and forward to the new ones) so existing imports keep building, but they are tagged deprecated and will be removed in a future major release.

This page is a cheat-sheet for the migration. New code should target the right-hand column directly.

Content negotiation

Same signatures, same semantics. The deprecated forms in middleware/seam.go are thin wrappers that call straight through.

// before
// import "github.com/go-openapi/runtime/middleware"
chosen := middleware.NegotiateContentType(r, offers, "application/json")

Full source: docs/examples/server/deprecatedshims/main.go

// after
// import "github.com/go-openapi/runtime/server-middleware/negotiate"
chosen := negotiate.ContentType(r, offers, "application/json")

Full source: docs/examples/server/deprecatedshims/main.go

See standalone / content negotiation for the full surface, including the v0.30 MIME-parameter-honouring default.

Header parsing

The shim package (middleware/header) re-exports everything via type aliases and forwarding functions, so existing code is binary-compatible. Update imports when convenient.

Doc UI handlers — SwaggerUI, RapiDoc, Redoc

The middleware shims preserve the option-struct calling convention. The new docui package uses functional options and accepts (next http.Handler, opts ...Option).

Field-to-option mapping for the *Opts structs:

Migration example:

// before
// import "github.com/go-openapi/runtime/middleware"

handler := middleware.SwaggerUI(middleware.SwaggerUIOpts{
	BasePath: "/",
	Path:     "docs",
	SpecURL:  "/swagger.json",
	Title:    "Pet store",
}, api)

Full source: docs/examples/server/deprecatedshims/main.go

// after
// import "github.com/go-openapi/runtime/server-middleware/docui"

handler := docui.SwaggerUI(api,
	docui.WithUIBasePath("/"),
	docui.WithUIPath("docs"),
	docui.WithSpecURL("/swagger.json"),
	docui.WithUITitle("Pet store"),
)

Full source: docs/examples/server/deprecatedshims/main.go

Methods on *Opts types that were only used to manipulate option structs (e.g. SwaggerUIOpts.EnsureDefaults) have been removed — they were not load-bearing.

See standalone / doc UIs for the full options reference, the middleware-factory shape (UseSwaggerUI, etc.) and a complete net/http example.

Why the split?

Two reasons:

• Dependency hygiene. The doc UI and negotiation helpers don’t need any OpenAPI machinery. Pulling them through middleware made every consumer transitively depend on go-openapi/spec, go-openapi/loads and go-openapi/validate. The standalone module has zero such transitive deps — handy for a service that only wants to serve a static spec and a Swagger UI from a vanilla net/http mux.
• API hygiene. The new functional options are easier to extend than option-struct fields, and let us keep adding knobs without growing struct surfaces. The deprecated shims paper over the older shape so old code keeps building.

The plan is to remove the shims in a future major release. Migrating when convenient is enough — there’s no urgency, but there’s no reason to keep new code on the old paths either.

Media types

server-middleware/mediatype provides the parsed value type, the matching rule and the helper used by both server-side Content-Type validation and Accept-header negotiation.

The MediaType value

type MediaType struct {
    Type    string             // lowercased on parse
    Subtype string             // lowercased on parse
    Params  map[string]string  // keys lowercased; values verbatim
    Q       float64            // extracted from "q="; not stored in Params
}

See MediaType on pkg.go.dev for the authoritative definition.

Parse accepts a single media type:

mt, err := mediatype.Parse("application/json;charset=utf-8;q=0.8")
// mt.Type    = "application"
// mt.Subtype = "json"
// mt.Params  = {"charset": "utf-8"}
// mt.Q       = 0.8

if errors.Is(err, mediatype.ErrMalformed) {
	// ↳ 400 Bad Request territory
	log.Println("malformed media type")
}

Full source: docs/examples/standalone/mediatypes/main.go

Parameter values are preserved verbatim, but comparisons are case-insensitive (charset=UTF-8 matches charset=utf-8). Wildcards */* and type/* are accepted on either side; */subtype is invalid and Parse rejects it.

Specificity

MediaType.Specificity() returns one of the constants below — useful when writing custom selection logic:

The asymmetric matching rule

MediaType.Matches(other) is asymmetric. The receiver is the bound (an allowed entry on the server side, or a candidate offer when matching against an Accept entry); the argument is the constraint (the actual request value, or the Accept entry being satisfied).

The rule:

1. Bare type/subtype must agree (with wildcards on either side).
2. If the receiver carries no parameters, any constraint is accepted regardless of its parameters.
3. Otherwise every (key, value) pair on the constraint must be present on the receiver, with case-insensitive value comparison. The receiver may carry additional parameters that the constraint does not list.

q-values are not considered by Matches — they belong to the negotiator (see Set.BestMatch).

The same direction is used in both call sites in the runtime:

MatchFirst — the validation primitive

func MatchFirst(allowed []string, actual string) (MediaType, bool, error)

See MatchFirst on pkg.go.dev for the authoritative signature.

Used when you need a yes/no answer plus the matched bound. Short-circuits on the first allowed entry that accepts actual (so the returned MediaType is not necessarily the most specific match — use Set.BestMatch if you need ranked selection).

Allowed entries that themselves fail to parse are skipped silently (they cannot match a well-formed actual).

Sets and BestMatch

type Set []MediaType

func ParseAccept(s string) Set
func (s Set) BestMatch(offered Set) (best MediaType, ok bool)

See Set, ParseAccept and Set.BestMatch on pkg.go.dev for the authoritative signatures.

ParseAccept parses a comma-separated list (e.g. an Accept header value), skipping malformed entries silently — be liberal in what you accept.

BestMatch ranks the offered set against the receiver Accept set:

1. Highest q-value wins.
2. Ties on q broken by the highest Specificity of the matching Accept entry.
3. Ties on specificity broken by earliest position in offered.

Accept entries with q=0 are treated as exclusions and never match. Returns ok=false if no offer matched any non-zero-q entry.

For the full algorithm — including how negotiate wires this up and the v0.30 parameter-honouring change — see tutorials / media-type selection and the next page, content negotiation.

Content negotiation

server-middleware/negotiate sits on top of mediatype and exposes two single-purpose helpers — one for Accept, one for Accept-Encoding.

ContentType — pick a response media type

func ContentType(
    r *http.Request,
    offers []string,
    defaultOffer string,
    opts ...Option,
) string

Returns the offer most acceptable to the request’s Accept header. If two offers match with equal weight, the more specific offer wins (text/* trumps */*; type/subtype trumps type/*); after that the earlier entry in offers wins. If no offer is acceptable, defaultOffer is returned.

// Pet is the demo resource served by the negotiation handler.
type Pet struct {
	XMLName xml.Name `json:"-"    xml:"pet"`
	Name    string   `json:"name" xml:"name"`
}

func pickContentType() {
	pet := Pet{Name: "Lassie"}
	offers := []string{mediaTypeJSON, mediaTypeXML}

	http.HandleFunc("/pet", func(w http.ResponseWriter, r *http.Request) {
		chosen := negotiate.ContentType(r, offers, mediaTypeJSON)
		w.Header().Set("Content-Type", chosen)

		switch chosen {
		case mediaTypeXML:
			_ = xml.NewEncoder(w).Encode(pet)
		default:
			_ = json.NewEncoder(w).Encode(pet)
		}
	})

	srv := &http.Server{
		Addr:              ":8080",
		ReadHeaderTimeout: readHeaderTimeout,
	}
	log.Fatal(srv.ListenAndServe())
}

Full source: docs/examples/standalone/contentnegotiation/main.go

When Accept is absent entirely, the first offer is returned unchanged.

Behaviour change in v0.30 — MIME parameters honoured

Pre-v0.30 the negotiator stripped MIME-type parameters before matching: an Accept of text/plain;charset=utf-8 matched an offer of text/plain;charset=ascii (the charset was thrown away). That was expedient but wrong; v0.30 honours parameters by default:

• Accept: text/plain;charset=utf-8 matches an offer of bare text/plain (offer carries no constraint — receiver-side params, asymmetric rule).
• Accept: text/plain;charset=utf-8 does not match an offer of text/plain;charset=ascii (charset values disagree).

If your producers and Accept clients use mismatched charset or version params that you treat as informational, opt out per call —

chosen := negotiate.ContentType(r, offers, "",
	negotiate.WithIgnoreParameters(true),
)

Full source: docs/examples/standalone/contentnegotiation/main.go

— or server-wide via the runtime’s middleware.Context:

ctx := middleware.NewContext(spec, api, nil).SetIgnoreParameters(true)

Full source: docs/examples/standalone/contentnegotiation/main.go

ContentEncoding — pick a response encoding

func ContentEncoding(r *http.Request, offers []string) string

Returns the best-matching offered encoding for the request’s Accept-Encoding header. Two offers tied on q go to the earlier one; no acceptable offer returns "" (so the caller can choose to send no encoding rather than substituting identity).

Encoding tokens have no parameters, so this function is unaffected by the v0.30 parameter-honouring change.

chosen := negotiate.ContentEncoding(r, []string{"gzip", "deflate"})
if chosen != "" {
	w.Header().Set("Content-Encoding", chosen)
}

Full source: docs/examples/standalone/contentnegotiation/main.go

Direct header parsing

If you only need raw header parsing without the typed MediaType layer (for example when implementing a different selection rule), drop down to negotiate/header:

specs := header.ParseAccept(r.Header, "Accept")
for _, s := range specs {
	// s.Value, s.Q, s.Params
	use(s)
}

Full source: docs/examples/standalone/contentnegotiation/main.go

Where it sits in the runtime pipeline

The full server pipeline calls ContentType (and the matching Content-Type validation through mediatype.MatchFirst) inside Context.BindValidRequest; see core / interfaces. The standalone module exposes the same primitives so you can drive negotiation from any net/http handler, with or without an OpenAPI spec in the picture.

Doc UIs & spec serving

server-middleware/docui ships ready-to-mount http.Handlers that serve the three popular OpenAPI documentation UIs and the spec document itself. Standard library only — no template engine, no asset bundler, no transitive OpenAPI dependency.

Two equivalent patterns

Each UI is exposed in two shapes; pick whichever fits your wiring style.

Direct handler wrap — SwaggerUI(next, opts...)

For when you already have an http.Handler you want to decorate.

api := myAPIHandler() // your application

handler := docui.SwaggerUI(api,
	docui.WithSpecURL("/swagger.json"),
	docui.WithUIBasePath("/"),
	docui.WithUIPath("docs"),
)

srv := &http.Server{
	Addr:              ":8080",
	Handler:           handler,
	ReadHeaderTimeout: readHeaderTimeout,
}

Full source: docs/examples/standalone/docui/main.go

Requests under the configured doc path render the UI; everything else falls through to next.

Middleware factory — UseSwaggerUI(opts...)

For composition with other middlewares (alice.New(...), your own chain, etc.):

mw := docui.UseSwaggerUI(
	docui.WithSpecURL("/swagger.json"),
	docui.WithUIPath("docs"),
)
mux.Handle("/", mw(api))

Full source: docs/examples/standalone/docui/main.go

Use* returns a func(http.Handler) http.Handler — the standard go-style middleware adapter.

Available UIs

The OAuth2 callback handler is the small static page Swagger UI redirects to after an OAuth2 authorization — mount it at the path you configure in your OAuth provider.

Common options

WithUITemplate panics at request time if the supplied template fails to parse or execute — fail loud, not silent. Reference docs for the templates each UI accepts:

• Redoc: https://github.com/Redocly/redoc/blob/main/docs/deployment/html.md
• RapiDoc: https://github.com/rapi-doc/RapiDoc
• Swagger UI: https://github.com/swagger-api/swagger-ui

Serving the spec document — ServeSpec / UseSpec

The UIs only render — they do not host the spec document themselves. Use the Spec helpers for that:

handler := docui.ServeSpec(specBytes, api,
	docui.WithSpecPath("/swagger.json"),
)

Full source: docs/examples/standalone/docui/main.go

or as middleware:

mw := docui.UseSpec(specBytes,
	docui.WithSpecPath("/swagger.json"),
)
mux.Handle("/", mw(api))

Full source: docs/examples/standalone/docui/main.go

If you want the spec path the UIs use to stay in sync with the path the spec is served from:

uiOpts := []docui.Option{docui.WithSpecURL("/swagger.json")}
specOpt := docui.WithSpecPathFromOptions(uiOpts...)

handler := docui.SwaggerUI(
	docui.ServeSpec(specBytes, api, specOpt),
	uiOpts...,
)

Full source: docs/examples/standalone/docui/main.go

Putting it together

A complete net/http server with no OpenAPI runtime in the picture:

//go:embed openapi.yaml
var spec []byte

func puttingItTogether() {
	api := http.NewServeMux()
	api.HandleFunc("/v1/ping", func(w http.ResponseWriter, _ *http.Request) {
		_, _ = w.Write([]byte("pong"))
	})

	handler := docui.SwaggerUI(
		docui.ServeSpec(spec, api,
			docui.WithSpecPath("/openapi.yaml"),
		),
		docui.WithSpecURL("/openapi.yaml"),
		docui.WithUIPath("docs"),
		docui.WithUITitle("Demo API"),
	)

	srv := &http.Server{
		Addr:              ":8080",
		Handler:           handler,
		ReadHeaderTimeout: readHeaderTimeout,
	}
	log.Fatal(srv.ListenAndServe())
}

Full source: docs/examples/standalone/docui/main.go

Visit:

• http://localhost:8080/docs — Swagger UI
• http://localhost:8080/openapi.yaml — the spec document
• http://localhost:8080/v1/ping — the application

Authentication & authorization

OpenAPI 2.0 defines four auth flavours; the runtime covers all four plus the orthogonal Authorizer step. The pages below walk one concrete scenario each — the first three cover the simplest cases, the rest progressively layer on scopes, composition and custom business rules.

When to use which

For the conceptual model (interfaces, lifecycle, where each stage fires), see server / security and core / interfaces.

• API key (single scheme)

  Simplest server-side auth — a single API key carried in a header (or query parameter), validated against a static map.
• HTTP Basic

  RFC 7617 Basic auth with realm and a WWW-Authenticate challenge on failure.
• Bearer + JWT

  OAuth2-style Bearer tokens carrying a JWT — verified locally, scope-checked against the operation’s required scopes.
• Composed schemes (AND / OR)

  Multiple security schemes per operation — AND inside an entry, OR between entries — with a single principal type.
• OAuth2 access-code (Google)

  Full OAuth2 access-code handshake against Google — login redirect, callback handler, token exchange and protected operations.
• Custom Authorizer (RBAC)

  Pluggable Authorizer that gates the principal for the matched operation — a worked role-based access control example, orthogonal to whichever Authenticator was used.
• Client-side credentials

  Attaching auth information to outgoing requests — Basic, API key, Bearer, composed writers, and a custom HMAC signer.