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.