v2.27.0

Sponsors

A big thank you to our new sponsors:

• vinogradovkonst
• miyamo2

Consider sponsoring the project!

Overview

Write Errors & Warnings to Stderr

When writing custom commands that output to stdout, sometimes an error or warning can be generated by Huma, which could add unwanted output to stdout. This has been updated to use stderr so it is easier to differentiate. This is useful for an openapi command that dumps the OpenAPI document to stdout as it is now safe to redirect it to a file even if warnings are generated.

Better Handling of Embedded Header Fields

When headers are embedded in the output struct they are now properly referenced in the documentation and the parent embedded struct itself is ignored (previously it would include the headers twice). For example, this now works as expected:

// PaginationOutput contains reusable response headers
// for implementing pagination
type PaginationOutput struct {
	Link   string `header:"Link" doc:"HTTP links for e.g. pagination"`
	Cursor string `header:"Cursor" doc:"Identifier that can be used to paginate. If the value is empty then there are no more pages to iterate over."`
}

// list_slates.go
type listSlateResponse struct {
	pagination.PaginationOutput
	Body []listSlateBody
}

Fiber UserContext Support

When using the Fiber adapter and getting items from the context it now first checks Fiber's UserContext before checking the underlying context for the value. This makes Huma easier to use with Fiber and Fiber-specific middleware. No change in behavior is needed, things should Just Work™️.

Remove Chi From Tests

The code has been refactored to remove reliance on Chi for the tests, simplifying the project overall and relying more on the standard library.

Fix Operation Callbacks

Operation callbacks mistakenly used the wrong type of map[string]*PathItem when it should really have been map[string]map[string]*PathItem instead. The structure should look something like this, which is now supported properly to document asynchronous callbacks that your operation supports:

paths:
  /create:
    post:
      callbacks:
        myEvent:
          "{$request.body#/callbackUrl}":
            post:
              requestBody: # Contents of the callback message
                …

Better Support for Embedded RawBody Field

It's now possible to embed the RawBody field and have things work. For example:

type RequestHeader struct {
	Test string `header:"Test"`
}

type EmbedGreeting struct {
	RawBody multipart.Form
}

type AnotherGreetingInput struct {
	RequestHeader
	EmbedGreeting
}

ContentTypeFilter Now Updates OpenAPI

If an operation output implements ContentTypeFilter, then this will be called with the default value application/json and the result used to build the OpenAPI document. For example this will result in application/ld+json in the OpenAPI rather than application/json:

type Response struct {
	Message string `json:"message" doc:"The message."`
}

func (r *Response) ContentType(t string) string {
	return "application/ld+json"
}

type Output struct {
	Body Response
}

Other Fixes

• Various doc fixes / improvements
• New linters enabled for better code quality

What's Changed

• fix: write errors/warnings to stderr rather than stdout by @sm3142 in #651
• Exclude embedded fields in response header docs by @lucaspopp-wbd in #656
• Propagate fiberCtx.UserContext() to huma.Context - Context() by @excavador in #659
• Chi is a dep even for pure go implementations, refactor its usage in the main package to pure go. by @fwilkerson in #661
• fix: operation callbacks shape by @danielgtaylor in #665
• feat: support embedded raw body fields by @danielgtaylor in #666
• fix: body with ContentTypeFilter should update OpenAPI by @danielgtaylor in #667
• fix oauth2-jwt.md mermaid rendering issue by @ssoroka-tc in #668
• docs: fix typos in request-validation.md by @alexandear in #671
• chore: enable unconvert and tenv linters by @alexandear in #672
• refactor: simplify error handling for multipart form reading by @alexandear in #673

New Contributors

• @sm3142 made their first contribution in #651
• @excavador made their first contribution in #659
• @fwilkerson made their first contribution in #661

Full Changelog: v2.26.0...v2.27.0