v2.15.0

Sponsors

A big thank you to our new sponsor:

• phoenixtechnologies-io (website)

Overview

Schema Discriminator Support

Basic support for the OpenAPI 3.1 discriminator which gives hints to clients that the value of a field defines the type of the response. This is not currently exposed via tags but can be used when manually creating schemas:

s := &huma.Schema{
	OneOf: []*huma.Schema{
		{Type: "object", Properties: map[string]*huma.Schema{
			"type": {Type: "string", Enum: []any{"foo"}},
			"foo":  {Type: "string"},
		}},
		{Type: "object", Properties: map[string]*huma.Schema{
			"type": {Type: "string", Enum: []any{"bar"}},
			"bar":  {Type: "string"},
		}},
	},
	Discriminator: &huma.Discriminator{
		PropertyName: "type",
		Mapping: map[string]string{
			"foo": "#/components/schemas/Foo",
			"bar": "#/components/schemas/Bar",
		},
	},
}

Anonymous Struct Name Hints

Allow providing name hints via field tags for anonymous structs defined inline. This gives a bit more control over the JSON Schema type names:

type EndpointInput struct {
  Body struct {
    SomeData string `json:"some_data"`
  } `name-hint:"SomeName"`
}

Better File Upload UI Support

A contentMediaType field is generated for fields which are format: "binary" which enables a better UI for uploading files in the generated docs.

Bug Fixes

The generated $schema field now uses http instead of https when the host is 127.0.0.1. Previously this was only the case for localhost.

Pointer types with custom schemas are now better supported by dereferencing the pointer to the underlying type before checking for the custom schema interface implementation.

The built-in Flow router has a fix applied to handle path params that are percent encoded with slashes. Fix has also been submitted upstream.

Fixed a possible panic in the schema link transformer when passed nil body types.

Updated the precondition error locations to match the rest of the project. request.headers.If-Match → headers.If-Match as we no longer explicitly state it's in the request. It's always in the request.

Fixed an example in the docs that was resulting in an error due to a typo.

What's Changed

• Use plain http in $schema for 127.0.0.1 by @davidolrik in #408
• fix: check if struct implements interface SchemaProvider after deref by @lennycampino in #413
• fix: Add support for Percent-Encoding RFC 3986 by @chilic in #411
• fix: more robust nil check for link transformer by @danielgtaylor in #418
• feat: basic schema discriminator support by @danielgtaylor in #419
• fix: precondition error location to match other errors by @danielgtaylor in #420
• Allow providing name hints using tags for anonymous body structs by @lsdch in #416
• fix: cli name example in docs by @danielgtaylor in #421
• Add contentMediaType field to generated schema when format is binary by @lsdch in #422

New Contributors

• @davidolrik made their first contribution in #408
• @lennycampino made their first contribution in #413
• @chilic made their first contribution in #411

Full Changelog: v2.14.0...v2.15.0