v2.13.0

Overview

This release includes some minor but important changes that may break some existing users by removing deprecated functionality. I'm really sorry for the potential breaks and will do my best to adhere more strictly to semantic versioning in the future. Be aware that these changes are not taken lightly and possible alternatives were considered. I have also tried to group all the small breaks/changes into a single release to mitigate repeated painful upgrades. Building this type of library is hard and I feel for your frustrations and appreciate your understanding!

As of this release, you can now build a full-fledged Huma service with zero additional hard dependencies (if using the Go 1.22+ built-in huma.ServeMux router and only JSON).

Removal of deprecated huma.NewCLI

Back in version 2.8.0 the huma.NewCLI functionality was deprecated in favor of humacli.New. The deprecated call is now removed.

Caution

This has the potential to break existing users, but is being treated as a bug fix to remove a hard dependency on spf13/cobra. If you are already using humacli.New there is no need to change anything.

Make CBOR support optional

CBOR is now made optional in the default config. If you wish to continue using it, you must opt-in to a new import, which automatically registers the format with the default configuration:

import (
  "github.com/danielgtaylor/huma/v2"

  _ "github.com/danielgtaylor/huma/v2/formats/cbor"
)

This new behavior is documented at https://huma.rocks/features/response-serialization/#default-formats. In the future this also makes it easier to support other additional formats without adding hard dependencies.

Warning

While not a breaking change per se, without adding the new import your clients will no longer be able to request CBOR and will get JSON responses instead.

humatest no longer requires Chi

The humatest package now uses a tiny internal router rather than relying on the Chi router, which introduced extra dependencies especially for people not using Chi as their main router package. You can continue to use humatest.Wrap to wrap any router you like.

Also new are humatest.DumpRequest/humatest.DumpResponse and humatest.PrintRequest/humatest.PrintResponse utility functions which function similar to httptest.DumpRequest/httptest.DumpResponse but pretty print the body JSON to make debugging and showing examples easier. Usage example: https://go.dev/play/p/QQ9Bi7iws12.

Caution

This is technically a small breaking change, but is being treated as a bug fix to remove the dependency and make the package more future-proof by not relying on any single external router package and returning http.Handler for the router instead.

Per-operation Middleware

You can now attach middleware to a huma.Operation during registration. These middlewares will only run for that specific operation rather than for all operations:

huma.Register(api, huma.Operation{
	Method: http.MethodGet,
	Path:   "/demo",
	Middlewares: huma.Middlewares{
		func(ctx huma.Context, next func(huma.Context)) {
			// TODO: implement middleware here...
			next(ctx)
		},
	},
}, func(ctx context.Context, input *struct{}) (*struct{}, error) {
	// TODO: implement handler here...
	return nil, nil
})

See also https://huma.rocks/features/middleware/#operations.

Add ctx.Status()

You can now get the response status from a huma.Context in router-agnostic middleware, enabling easier logging/metrics/traces of the response status code.

func MyMiddleware(ctx huma.Context, next func(huma.Context)) {
	next(ctx)
	fmt.Println("Response status is", ctx.Status())
}

Better parameter descriptions

Some tools, notably SwaggerUI, require parameters to have descriptions to display properly (descriptions in the schema are not sufficient). These are now generated by Huma, so users opting to render docs with SwaggerUI should now get nicer output.

Bug Fixes

• The humafiber adapter accepts the correct group interface now.
• Schema name text transformations for generics are now applied to hints as well as generated names
• Do not crash when reflect.StructOf fails in schema link transformer
• Use errors.As when looking for huma.StatusError to enable error wrapping
• Better error messages when missing OpenAPI config

What's Changed

• fix: NewWithGroup accepting fiber.Router by @barklan in #361
• fix: remove deprecated cli functionality to limit dependencies by @danielgtaylor in #363
• fix: apply schema name text transforms to type hints by @danielgtaylor in #367
• fix: vendor casing library by @danielgtaylor in #368
• fix: do not require Chi for humatest by @danielgtaylor in #370
• Add the ability to get ctx.Status() by @ssoroka-tc in #369
• feat: add param descriptions from schemas by @danielgtaylor in #374
• fix: catch reflect.StructOf panics in schema transformer by @danielgtaylor in #375
• fix: use errors.As to get StatusError, enabling wrapping by @danielgtaylor in #381
• feat: add per-operation router-agnostic middleware by @danielgtaylor in #382
• must specify openapi config by @ssoroka in #383
• fix: make cbor support optional by @danielgtaylor in #372

New Contributors

• @barklan made their first contribution in #361
• @ssoroka-tc made their first contribution in #369
• @ssoroka made their first contribution in #383

Full Changelog: v2.12.0...v2.13.0