huma

README

• What is huma?
• Install
• Example
• Documentation

A modern, simple, fast & flexible micro framework for building HTTP REST/RPC APIs in Go backed by OpenAPI 3 and JSON Schema. Pronounced IPA: /'hjuːmɑ/. The goals of this project are to provide:

• Incremental adoption for teams with existing services
  • Bring your own router, middleware, and logging/metrics
  • Extensible OpenAPI & JSON Schema layer to document existing routes
• A modern REST or HTTP RPC API backend framework for Go developers
  • Described by OpenAPI 3.1 & JSON Schema
• Guard rails to prevent common mistakes
• Documentation that can't get out of date
• High-quality generated developer tooling

Features include:

• Declarative interface on top of your router of choice:
  • Operation & model documentation
  • Request params (path, query, or header)
  • Request body
  • Responses (including errors)
  • Response headers
• JSON Errors using RFC7807 and application/problem+json by default (but can be changed)
• Per-operation request size limits with sane defaults
• Content negotiation between server and client
  • Support for JSON (RFC 8259) and CBOR (RFC 7049) content types via the Accept header with the default config.
• Conditional requests support, e.g. If-Match or If-Unmodified-Since header utilities.
• Optional automatic generation of PATCH operations that support:
  • RFC 7386 JSON Merge Patch
  • RFC 6902 JSON Patch
  • Shorthand patches
• Annotated Go types for input and output models
  • Generates JSON Schema from Go types
  • Static typing for path/query/header params, bodies, response headers, etc.
  • Automatic input model validation & error handling
• Documentation generation using Stoplight Elements
• Optional CLI built-in, configured via arguments or environment variables
  • Set via e.g. -p 8000, --port=8000, or SERVICE_PORT=8000
  • Startup actions & graceful shutdown built-in
• Generates OpenAPI for access to a rich ecosystem of tools
  • Mocks with API Sprout or Prism
  • SDKs with OpenAPI Generator or oapi-codegen
  • CLI with Restish
  • And plenty more
• Generates JSON Schema for each resource using optional describedby link relation headers as well as optional $schema properties in returned objects that integrate into editors for validation & completion.

This project was inspired by FastAPI. Logo & branding designed by Kari Taylor.

Install

Install via go get. Note that Go 1.20 or newer is required.

# After: go mod init ...
go get -u github.com/danielgtaylor/huma/v2

Example

Here is a complete basic hello world example in Huma, that shows how to initialize a Huma app complete with CLI, declare a resource operation, and define its handler function.

package main

import (
	"context"
	"fmt"
	"net/http"

	"github.com/danielgtaylor/huma/v2"
	"github.com/danielgtaylor/huma/v2/adapters/humachi"
	"github.com/go-chi/chi/v5"
)

// Options for the CLI.
type Options struct {
	Port int `help:"Port to listen on" short:"p" default:"8888"`
}

// GreetingInput represents the greeting operation request.
type GreetingInput struct {
	Name string `path:"name" maxLength:"30" example:"world" doc:"Name to greet"`
}

// GreetingOutput represents the greeting operation response.
type GreetingOutput struct {
	Body struct {
		Message string `json:"message" example:"Hello, world!" doc:"Greeting message"`
	}
}

func main() {
	// Create a CLI app which takes a port option.
	cli := huma.NewCLI(func(hooks huma.Hooks, options *Options) {
		// Create a new router & API
		router := chi.NewMux()
		api := humachi.New(router, huma.DefaultConfig("My API", "1.0.0"))

		// Register GET /greeting/{name}
		huma.Register(api, huma.Operation{
			OperationID: "get-greeting",
			Summary:     "Get a greeting",
			Method:      http.MethodGet,
			Path:        "/greeting/{name}",
		}, func(ctx context.Context, input *GreetingInput) (*GreetingOutput, error) {
			resp := &GreetingOutput{}
			resp.Body.Message = fmt.Sprintf("Hello, %s!", input.Name)
			return resp, nil
		})

		// Tell the CLI how to start your router.
		hooks.OnStart(func() {
			http.ListenAndServe(fmt.Sprintf(":%d", options.Port), router)
		})
	})

	// Run the CLI. When passed no commands, it starts the server.
	cli.Run()
}

You can test it with go run greet.go (optionally pass --port to change the default) and make a sample request using Restish (or curl):

# Get the message from the server
$ restish :8888/greeting/world
HTTP/1.1 200 OK
...
{
	$schema: "http://localhost:8888/schemas/GreetingOutputBody.json",
	message: "Hello, world!"
}

Even though the example is tiny you can also see some generated documentation at http://localhost:8888/docs. The generated OpenAPI is available at http://localhost:8888/openapi.json or http://localhost:8888/openapi.yaml.

Documentation

Official Go package documentation can always be found at https://pkg.go.dev/github.com/danielgtaylor/huma/v2. Below is an introduction to the various features available in Huma.

🐳 Hi there! I'm the happy Huma whale here to provide help. You'll see me leave helpful tips down below.

BYOR (Bring Your Own Router)

Huma is designed to be router-agnostic to enable incremental adoption in existing and new services across a large number of organizations. This means you can use any router you want, or even write your own. The only requirement is and implementation of a small huma.Adapter interface. This is how Huma integrates with your router.

Adapters are in the adapters directory and named after the router they support. Many common routers are supported out of the box:

• chi via humachi
• gin via humagin
• gorilla/mux via humamux
• httprouter via humahttprouter
• Fiber via humafiber

Adapters are instantiated by wrapping your router and providing a Huma configuration object which describes the API. Here is a simple example using Chi:

// Create your router.
app := chi.NewMux()

// Wrap the router with Huma to create an API instance.
api := humachi.New(app, huma.DefaultConfig("My API", "1.0.0"))

// Register your operations with the API.
// ...

// Start the server!
http.ListenAndServe(":8888", r)

🐳 Writing your own adapter is quick and simple, and PRs are accepted for additional adapters to be built-in.

Middleware

Huma has support two variants of middlewares:

1. Router-specific - works at the router level, i.e. before router-agnostic middleware, you can use any middleware that is implemented for your router.
2. Router-agnostic - runs in the Huma processing chain, i.e. after calls to router-specific middleware.

Router-specific

Each router implementation has its own middlewares, you can use this middlewares with huma v2 framework.

Chi router example:

router := chi.NewMux()
router.Use(jwtauth.Verifier(tokenAuth))
api := humachi.New(router, defconfig)

🐳 Huma v1 middleware is compatible with Chi v4, so if you use that router with Huma v2 you can continue to use the Huma v1 middleware.

Router-agnostic

You can write you own Huma v2 middleware without any dependency to the specific router implementation.

Example:

func MyMiddleware(ctx huma.Context, next func(huma.Context)) {
    // I don't do anything
    next(ctx)
}
func NewHumaAPI() huma.API {
    // ...
    api := humachi.New(router, config)
    // OR api := humagin.New(router, config)
    api.UseMiddleware(MyMiddleware)
}

Open API Generation & Extensibility

Huma generates Open API 3.1.0 compatible JSON/YAML specs and provides rendered documentation automatically. Every operation that is registered with the API is included in the spec by default. The operation's inputs and outputs are used to generate the request and response parameters / schemas.

The API config controls where the OpenAPI, docs, and schemas are available. The default config uses /openapi.json, /docs, and /schemas respectively. You can change these to whatever you want, or disable them entirely by leaving them blank.

You may want to customize the generated Open API spec. With Huma v2 you have full access and can modify it as needed in the API configuration or when registering operations. For example, to set up a security scheme:

config := huma.DefaultConfig("My API", "1.0.0")
config.Components.SecuritySchemes = map[string]*huma.SecurityScheme{
		"bearer": {
			Type: "http",
			Scheme: "bearer",
			BearerFormat: "JWT",
		},
	}
api := humachi.New(router, config)

huma.Register(api, huma.Operation{
	OperationID: "get-greeting",
	Method:      http.MethodGet,
	Path:        "/greeting/{name}",
	Summary:     "Get a greeting",
	Security: []map[string][]string{
		{"bearer": {}},
	},
}, func(ctx context.Context, input *GreetingInput) (*GreetingOutput, error) {
	// ...
})

🐳 See the OpenAPI 3.1 spec for everything that can be set and how it is expected to be used.

OpenAPI Settings Composition

Because you have full access to the OpenAPI spec, you can compose it however you want and write convenience functions to make things more straightforward. The above example could be made easier to read:

config := huma.DefaultConfig("My API", "1.0.0")
config = withBearerAuthScheme(config)

api := humachi.New(router, config)

huma.Register(api, withBearerAuth(huma.Operation{
	OperationID: "get-greeting",
	Method:      http.MethodGet,
	Path:        "/greeting/{name}",
	Summary:     "Get a greeting",
}), func(ctx context.Context, input *GreetingInput) (*GreetingOutput, error) {
	// ...
})

Set this up however you like. Even the huma.Register function can be wrapped or replaced by your organization to ensure that all operations are registered with the same settings.

Custom OpenAPI Extensions

Custom extensions to the OpenAPI are supported via the Extensions field on most OpenAPI structs:

config := huma.DefaultConfig("My API", "1.0.0")
config.Extensions = map[string]any{
	"my-extension": "my-value",
}

Anything in the Extensions map will be flattened during serialization so that its fields are peers with the Extensions peers in the OpenAPI spec. For example, the above would result in:

{
  "openapi": "3.1.0",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  },
  "my-extension": "my-value"
}

JSON Schema

Using the default Huma config (or manually via the huma.SchemaLinkTransformer), each resource operation returns a describedby HTTP link relation header which references a JSON-Schema file. These schemas use the config.SchemasPath to serve their content. For example:

Link: </schemas/Note.json>; rel="describedby"

Object resources (i.e. not arrays or simple scalars) can also optionally return a $schema property with such a link, which enables the described-by relationship to outlive the HTTP request (i.e. saving the body to a file for later editing) and enables some editors like VSCode to provide code completion and validation as you type.

{
  "$schema": "http://localhost:8888/schemas/Note.json",
  "title": "I am a note title",
  "contents": "Example note contents",
  "labels": ["todo"]
}

Operations which accept objects as input will ignore the $schema property, so it is safe to submit back to the API, aka "round-trip" the data.

🐳 The $schema field is incredibly powerful when paired with Restish's edit command, giving you a quick and easy way to edit strongly-typed resources in your favorite editor.

Schema Registry

Huma uses a customizable registry to keep track of all the schemas that have been generated from Go structs. This is used to avoid generating the same schema multiple times, and to provide a way to reference schemas by name for OpenAPI operations & hosted JSON Schemas.

The default schema implementation uses a map to store schemas by name,generated from the Go type name without the package name. This supports recursive schemas and generates simple names like Thing or ThingList. Note that by design it does not support multiple models with the same name in different packages.

You can create your own registry with custom behavior by implementing the huma.Registry interface and setting it on config.Components.Schemas when creating your API.

Operations

Operations are at the core of Huma. They map an HTTP method verb and resource path to a handler function with well-defined inputs and outputs. Operations are created using the huma.Register function:

huma.Register(api, huma.Operation{
	OperationID: "your-operation-name",
	Method:      http.MethodGet,
	Path:        "/path/to/resource/{id}",
	Summary:     "A short description of the operation",
}, func(ctx context.Context, input *YourInput) (*YourOutput, error) {
	// ... Implementation goes here ...
})

🐳 If following REST-ish conventions, operation paths should be nouns, and plural if they return more than one item. Good examples: /notes, /likes, /users/{user-id}, /videos/{video-id}/stats, etc. Huma does not enforce this or care, so RPC-style paths are also fine to use. Use what works best for you and your team.

The operation handler function always has the following generic format, where Input and Output are custom structs defined by the developer that represent the entirety of the request (path/query/header params & body) and response (headers & body), respectively:

func(context.Context, *Input) (*Output, error)

There are many options available for configuring OpenAPI settings for the operation, and custom extensions are supported as well. See the huma.Operation struct for more details.

🐳 Did you know? The OperationID is used to generate friendly CLI commands in Restish and used when generating SDKs! It should be unique, descriptive, and easy to type.

Input & Output Models

Inputs and outputs are always structs that represent the entirety of the incoming request or outgoing response. This is a deliberate design decision to make it easier to reason about the data flow in your application. It also makes it easier to share code as well as generate documentation and SDKs.

Request Model

Requests can have parameters and/or a body as input to the handler function. Inputs use standard Go structs with special fields and/or tags. Here are the available tags:

Tag	Description	Example
path	Name of the path parameter	path:"thing-id"
query	Name of the query string parameter	query:"q"
header	Name of the header parameter	header:"Authorization"
required	Mark a query/header param as required	required:"true"

🐳 The required tag is discouraged and is only used for query/header params, which should generally be optional for clients to send.

The following parameter types are supported out of the box:

Type	Example Inputs
bool	true, false
[u]int[16/32/64]	1234, 5, -1
float32/64	1.234, 1.0
string	hello, t
time.Time	2020-01-01T12:00:00Z
slice, e.g. []int	1,2,3, tag1,tag2

For example, if the parameter is a query param and the type is []string it might look like ?tags=tag1,tag2 in the URI.

The special struct field Body will be treated as the input request body and can refer to any other type or you can embed a struct or slice inline. If the body is a pointer, then it is optional. All doc & validation tags are allowed on the body in addition to these tags:

Tag	Description	Example
contentType	Override the content type	contentType:"application/octet-stream"
required	Mark the body as required	required:"true"

RawBody []byte can also be used alongside Body or standalone to provide access to the []byte used to validate & parse Body, or to the raw input without any validation/parsing.

Example:

type MyInput struct {
	ID      string `path:"id"`
	Detail  bool   `query:"detail" doc:"Show full details"`
	Auth    string `header:"Authorization"`
	Body    MyBody
	RawBody []byte
}

A request to such an endpoint might look like:

# Via high-level operations:
$ restish api my-op 123 --detail=true --authorization=foo <body.json

# Via URL:
$ restish api/my-op/123?detail=true -H "Authorization: foo" <body.json

🐳 You can use RawBody []byte without a corresponding Body field in order to support file uploads.

Validation

Go struct tags are used to annotate inputs/output structs with information that gets turned into JSON Schema for documentation and validation.

The standard json tag is supported and can be used to rename a field and mark fields as optional using omitempty. The following additional tags are supported on model fields:

Tag	Description	Example
doc	Describe the field	doc:"Who to greet"
format	Format hint for the field	format:"date-time"
enum	A comma-separated list of possible values	enum:"one,two,three"
default	Default value	default:"123"
minimum	Minimum (inclusive)	minimum:"1"
exclusiveMinimum	Minimum (exclusive)	exclusiveMinimum:"0"
maximum	Maximum (inclusive)	maximum:"255"
exclusiveMaximum	Maximum (exclusive)	exclusiveMaximum:"100"
multipleOf	Value must be a multiple of this value	multipleOf:"2"
minLength	Minimum string length	minLength:"1"
maxLength	Maximum string length	maxLength:"80"
pattern	Regular expression pattern	pattern:"[a-z]+"
minItems	Minimum number of array items	minItems:"1"
maxItems	Maximum number of array items	maxItems:"20"
uniqueItems	Array items must be unique	uniqueItems:"true"
minProperties	Minimum number of object properties	minProperties:"1"
maxProperties	Maximum number of object properties	maxProperties:"20"
example	Example value	example:"123"
readOnly	Sent in the response only	readOnly:"true"
writeOnly	Sent in the request only	writeOnly:"true"
deprecated	This field is deprecated	deprecated:"true"

Parameters have some additional validation tags:

Tag	Description	Example
hidden	Hide parameter from documentation	hidden:"true"

Resolvers

Sometimes the built-in validation isn't sufficient for your use-case, or you want to do something more complex with the incoming request object. This is where resolvers come in.

Any input struct can be a resolver by implementing the huma.Resolver or huma.ResolverWithPath interface, including embedded structs. Each resolver takes the current context and can return a list of exhaustive errors. For example:

// MyInput demonstrates inputs/transformation
type MyInput struct {
	Host   string
	Name string `query:"name"`
}

func (m *MyInput) Resolve(ctx huma.Context) []error {
	// Get request info you don't normally have access to.
	m.Host = ctx.Host()

	// Transformations or other data validation
	m.Name = strings.Title(m.Name)

	return nil
}

// Then use it like any other input struct:
huma.Register(api, huma.Operation{
	OperationID: "list-things",
	Method:      http.MethodGet,
	Path:        "/things",
	Summary:     "Get a filtered list of things",
}, func(ctx context.Context, input *MyInput) (*YourOutput, error) {
	fmt.Printf("Host: %s\n", input.Host)
	fmt.Printf("Name: %s\n", input.Name)
})

It is recommended that you do not save the context object passed to the Resolve method for later use.

For deeply nested structs within the request body, you may not know the current location of the field being validated (e.g. it may appear in multiple places or be shared by multiple request objects). The huma.ResolverWithPath interface provides a path prefix that can be used to generate the full path to the field being validated. It uses a huma.PathBuffer for efficient path generation reusing a shared buffer. For example:

func (m *MyInput) Resolve(ctx huma.Context, prefix *huma.PathBuffer) []error {
	return []error{&huma.ErrorDetail{
		Message: "Foo has a bad value",
		Location: prefix.With("foo")
		Value: m.Foo,
	}}
}

🐳 Prefer using built-in validation over resolvers whenever possible, as it will be better documented and is also usable by OpenAPI tooling to provide a better developer experience.

Resolver Errors

Resolvers can set errors as needed and Huma will automatically return a 400-level error response before calling your handler. This makes resolvers a good place to run additional complex validation steps so you can provide the user with a set of exhaustive errors.

type MyInput struct {
	Host   string
}

func (m *MyInput) Resolve(ctx huma.Context) []error {
	if m.Host = ctx.Host(); m.Host == "localhost" {
		return []error{&huma.ErrorDetail{
			Message: "Unsupported host value!",
			Location: "request.host",
			Value: m.Host,
		}}
	}
	return nil
}

It is also possible for resolvers to return custom HTTP status codes for the response, by returning an error which satisfies the huma.StatusError interface. Errors are processed in the order they are returned and the last one wins, so this feature should be used sparingly. For example:

type MyInput struct{}

func (i *MyInput) Resolve(ctx huma.Context) []error {
	return []error{huma.Error403Forbidden("nope")}
}

🐳 Exhaustive errors lessen frustration for users. It's better to return three errors in response to one request than to have the user make three requests which each return a new different error.

Input Composition

Because inputs are just Go structs, they are composable and reusable. For example:

type AuthParam struct {
	Authorization string `header:"Authorization"`
}

type PaginationParams struct {
	Cursor string `query:"cursor"`
	Limit  int    `query:"limit"`
}

// ... Later in the code
huma.Register(api, huma.Operation{
	OperationID: "list-things",
	Method:      http.MethodGet,
	Path:        "/things",
	Summary:     "Get a filtered list of things",
}, func(ctx context.Context, input struct {
	// Embed both structs to compose your input.
	AuthParam
	PaginationParams
}) {
	fmt.Printf("Auth: %s, Cursor: %s, Limit: %d\n", input.Authorization, input.Cursor, input.Limit)
}

Request Deadlines & Timeouts

A combination of the server and the request context can be used to control deadlines & timeouts. Go's built-in HTTP server supports a few timeout settings:

srv := &http.Server{
	ReadTimeout:       5 * time.Second,
	WriteTimeout:      5 * time.Second,
	IdleTimeout:       30 * time.Second,
	ReadHeaderTimeout: 2 * time.Second,
	// ...
}

The Huma request context (accessible via resolvers) can be used to set a read deadline, which can be used to process large or streaming inputs:

type MyInput struct {}

func (m *MyInput) Resolve(ctx huma.Context) []error {
	ctx.SetReadDeadline(time.Now().Add(5 * time.Second))
}

Additionally, a context.Context can be used to set a deadline for dependencies like databases:

// Create a new context with a 10 second timeout.
newCtx, cancel := context.WithTimeout(ctx, 10 * time.Second)
defer cancel()

// Use the new context for any dependencies.
result, err := myDB.Get(newCtx, /* ... */)
if err != nil {
	// Deadline may have been hit, handle it here!
}

Request Body Size Limits

By default each operation has a 1 MiB request body size limit. This can be changed by setting huma.Operation.MaxBodyBytes to a different value when registering the operation. If the request body is larger than the limit then a 413 Request Entity Too Large error will be returned.

Response Model

Responses can have an optional status code, headers, and/or body. Like inputs, they use standard Go structs. Here are the available tags:

Tag	Description	Example
header	Name of the response header	header:"Authorization"

The special struct field Status with a type of int is used to optionally communicate a dynamic response status code from the handler (you should not need this most of the time!). If not present, the default is to use 200 for responses with bodies and 204 for responses without a body. Use huma.Operation.DefaultStatus at operation registration time to override. Note: it is much more common to set the default status code than to need a Status field in your response struct!

The special struct field Body will be treated as the response body and can refer to any other type or you can embed a struct or slice inline. Use a type of []byte to bypass serialization. A default Content-Type header will be set if none is present, selected via client-driven content negotiation with the server based on the registered serialization types.

Example:

type MyOutput struct {
	Status       int
	LastModified time.Time `header:"Last-Modified"`
	Body         MyBody
}

Streaming Responses

The response Body can also be a callback function taking a huma.Context to facilitate streaming. The huma.StreamResponse utility makes this easy to return:

func handler(ctx context.Context, input *MyInput) (*huma.StreamResponse, error) {
	return &huma.StreamResponse{
		Body: func(ctx huma.Context) {
			// Write header info before streaming the body.
			ctx.SetHeader("Content-Type", "text/my-stream")
			writer := ctx.BodyWriter()

			// Update the write deadline to give us extra time.
			if d, ok := bw.(interface{ SetWriteDeadline(time.Time) error }); ok {
				d.SetWriteDeadline(time.Now().Add(5 * time.Second))
			} else {
				fmt.Println("warning: unable to set write deadline")
			}

			// Write the first message, then flush and wait.
			writer.Write([]byte("Hello, I'm streaming!"))
			if f, ok := writer.(http.Flusher); ok {
				f.Flush()
			} else {
				fmt.Println("error: unable to flush")
			}

			time.Sleep(3 * time.Second)

			// Write the second message.
			writer.Write([]byte("Hello, I'm still streaming!"))
		},
	}, nil
}

Also take a look at http.ResponseController which can be used to set timeouts, flush, etc in one simple interface.

🐳 The sse package provides a helper for streaming Server-Sent Events (SSE) responses that is easier to use than the above example!

Generated Schema Customization

Schemas that are generated for input/output bodies can be customized in a couple of different ways. First, when registering your operation you can provide your own request and/or response schemas if you want to override the entire body. The automatic generation only applies when you have not provided your own schema in the OpenAPI.

Second, this can be done on a per-field basis by making a struct that implements a special interface to get a schema, allowing you to e.g. encapsulate additional functionality within that field. This is the interface:

// SchemaProvider is an interface that can be implemented by types to provide
// a custom schema for themselves, overriding the built-in schema generation.
// This can be used by custom types with their own special serialization rules.
type SchemaProvider interface {
	Schema(r huma.Registry) *huma.Schema
}

The huma.Registry is passed to you and can be used to get schemas or refs for any embedded structs. Here is an example, where we want to know if a field was omitted vs. null vs. a value when sent as part of a request body. First we start by defininig the custom generic struct:

// OmittableNullable is a field which can be omitted from the input,
// set to `null`, or set to a value. Each state is tracked and can
// be checked for in handling code.
type OmittableNullable[T any] struct {
	Sent  bool
	Null  bool
	Value T
}

// UnmarshalJSON unmarshals this value from JSON input.
func (o *OmittableNullable[T]) UnmarshalJSON(b []byte) error {
	if len(b) > 0 {
		o.Sent = true
		if bytes.Equal(b, []byte("null")) {
			o.Null = true
			return nil
		}
		return json.Unmarshal(b, &o.Value)
	}
	return nil
}

// Schema returns a schema representing this value on the wire.
// It returns the schema of the contained type.
func (o OmittableNullable[T]) Schema(r huma.Registry) *huma.Schema {
	return r.Schema(reflect.TypeOf(o.Value), true, "")
}

This is how it can be used in an operation:

type MyResponse struct {
	Body struct {
		Message string `json:"message"`
	}
}

huma.Register(api, huma.Operation{
	OperationID: "omittable",
	Method:      http.MethodPost,
	Path:        "/omittable",
	Summary:     "Omittable / nullable example",
}, func(ctx context.Context, input *struct {
	// Making the body a pointer makes it optional, as it may be `nil`.
	Body *struct {
		Name OmittableNullable[string] `json:"name,omitempty" maxLength:"10"`
	}
}) (*MyResponse, error) {
	resp := &MyResponse{}
	if input.Body == nil {
		resp.Body.Message = "Body was not sent"
	} else if !input.Body.Name.Sent {
		resp.Body.Message = "Name was omitted from the request"
	} else if input.Body.Name.Null {
		resp.Body.Message = "Name was set to null"
	} else {
		resp.Body.Message = "Name was set to: " + input.Body.Name.Value
	}
	return resp, nil
})

If you go to view the generated docs, you will see that the type of the name field is string and that it is optional, with a max length of 10, indicating that the custom schema was correctly used in place of one generated for the OmittableNullable[string] struct.

See https://github.com/danielgtaylor/huma/blob/main/examples/omit/main.go for a full example along with how to call it. This just scratches the surface of what's possible with custom schemas for fields.

Exhaustive Errors

Errors use RFC 7807 and return a structure that looks like:

{
  "status": 504,
  "title": "Gateway Timeout",
  "detail": "Problem with HTTP request",
  "errors": [
    {
      "message": "Get \"https://httpstat.us/418?sleep=5000\": context deadline exceeded"
    }
  ]
}

The errors field is optional and may contain more details about which specific errors occurred.

It is recommended to return exhaustive errors whenever possible to prevent user frustration with having to keep retrying a bad request and getting back a different error. Input parameters validation, body validation, resolvers, etc all support returning exhaustive errors.

While every attempt is made to return exhaustive errors within Huma, each individual response can only contain a single HTTP status code. The following chart describes which codes get returned and when:

flowchart TD
	Request[Request has errors?] -->|yes| Panic
	Request -->|no| Continue[Continue to handler]
	Panic[Panic?] -->|yes| 500
	Panic -->|no| RequestBody[Request body too large?]
	RequestBody -->|yes| 413
	RequestBody -->|no| RequestTimeout[Request took too long to read?]
	RequestTimeout -->|yes| 408
	RequestTimeout -->|no| ParseFailure[Cannot parse input?]
	ParseFailure -->|yes| 400
	ParseFailure -->|no| ValidationFailure[Validation failed?]
	ValidationFailure -->|yes| 422
	ValidationFailure -->|no| 400

This means it is possible to, for example, get an HTTP 408 Request Timeout response that also contains an error detail with a validation error for one of the input headers. Since request timeout has higher priority, that will be the response status code that is returned.

Response Transformers

Router middleware operates on router-specific request & response objects whose bodies are []byte slices or streams. Huma operations operate on specific struct instances. Sometimes there is a need to generically operate on structured response data after the operation handler has run but before the response is serialized to bytes. This is where response transformers come in.

flowchart LR
	Request --> Middleware
	Middleware --> Unmarshal
	subgraph Huma
		Unmarshal --> Handler
		Handler --> Transformer
		Transformer --> Marshal
	end
	Marshal --> Response

	style Transformer stroke:#f9f,stroke-width:2px,stroke-dasharray: 5 5

Response transformers enable you to modify the response on the fly. For example, you could add a Link header to the response to indicate that the response body is described by a JSON Schema. This is done by implementing the huma.Transformer interface and registering it with the API. See the huma.SchemaLinkTransformer for an example.

Serialization Formats

Huma supports custom serialization formats by implementing the huma.Format interface. Serialization formats are set on the API configuration at API creation time and selected by client-driven content negotiation using the Accept or Content-Type headers. The config.Formats maps either a content type name or extension (suffix) to a huma.Format instance.

The default configuration for Huma includes support for JSON (RFC 8259) and CBOR (RFC 7049) content types via the Accept header. This is done by registering the following content types using huma.DefaultJSONFormat & huma.DefaultCBORFormat:

• application/json
• Anything ending with +json
• application/cbor
• Anything ending with +cbor

🐳 You can easily add support for additional serialization formats, including binary formats like Protobuf if desired.

Content Negotiation

Content negotiation allows clients to select the content type they are most comfortable working with when talking to the API. For request bodies, this uses the Content-Type header. For response bodies, it uses the Accept header. If none are present then JSON is usually selected as the default / preferred content type.

See the negotiation package for more info.

CLI

Huma ships with a built-in lightweight utility to wrap your service with a CLI, enabling you to run it with different arguments and easily write custom commands to do things like print out the OpenAPI or run on-demand database migrations.

The CLI options use a similar strategy to input & output structs, enabling you to use the same pattern for validation and documentation of command line arguments. It uses Cobra & Viper under the hood, enabling automatic environment variable binding and more.

// First, define your input options.
type Options struct {
	Debug bool   `doc:"Enable debug logging"`
	Host  string `doc:"Hostname to listen on."`
	Port  int    `doc:"Port to listen on." short:"p" default:"8888"`
}

func main() {
	// Then, create the CLI.
	cli := huma.NewCLI(func(hooks huma.Hooks, opts *Options) {
		fmt.Printf("I was run with debug:%v host:%v port%v\n",
			opts.Debug, opts.Host, opts.Port)
	})

	// Run the thing!
	cli.Run()
}

You can then run the CLI with and see the results:

$ go run main.go
I was run with debug:false host: port:8888

To do useful work, you will want to register a handler for the default start command and optionally a way to gracefully shutdown the server:

cli := huma.NewCLI(func(hooks huma.Hooks, opts *Options) {
	hooks.OnStart(func() {
		// Start your server here
		http.ListenAndServe(
			fmt.Sprintf("%s:%d", opts.Host, opts.Port), myRouter,
		)
	})

	hooks.OnStop(func() {
		// Gracefully shutdown your server here
		// ...
	})
})

🐳 Option fields are automatically converted to --kebab-casing for use on the command line. If you want to use a different name, use the name struct tag to override the default behavior!

Custom Options

Custom options are defined by adding to your options struct. The following types are supported:

Type	Example Inputs
bool	true, false
int / int64	1234, 5, -1
string	prod, http://api.example.tld/

The following struct tags are available:

Tag	Description	Example
default	Default value (parsed automatically)	default:"123"
doc	Describe the option	doc:"Who to greet"
name	Override the name of the option	name:"my-option-name"
short	Single letter short name for the option	short:"p" for -p

Custom Commands

You can access the root cobra.Command via cli.Root() and add new custom commands via cli.Root().AddCommand(...). For example, to have a command print out the generated OpenAPI:

var api huma.API

// ... set up the CLI, create the API wrapping the router ...

cli.Root().AddCommand(&cobra.Command{
	Use:   "openapi",
	Short: "Print the OpenAPI spec",
	Run: func(cmd *cobra.Command, args []string) {
		b, _ := yaml.Marshal(api.OpenAPI())
		fmt.Println(string(b))
	},
})

Now you can run your service and use the new command: go run main.go openapi.

If you want to access your custom options struct with custom commands, use the huma.WithOptions(func(cmd *cobra.Command, args []string, options *YourOptions)) func(cmd *cobra.Command, args []string) utitity function. It ensures the options are parsed and available before running your command.

🐳 You can also overwite cli.Root().Run to completely customize how you run the server. Or just ditch the cli package altogether!

Additional Features

Conditional Requests

There are built-in utilities for handling conditional requests, which serve two broad purposes:

1. Sparing bandwidth on reading a document that has not changed, i.e. "only send if the version is different from what I already have"
2. Preventing multiple writers from clobbering each other's changes, i.e. "only save if the version on the server matches what I saw last"

Adding support for handling conditional requests requires four steps:

1. Import the github.com/danielgtaylor/huma/conditional package.
2. (optional) Add the response definition (304 Not Modified for reads or 412 Precondition Failed for writes)
3. Add conditional.Params to your input struct.
4. Check if conditional params were passed and handle them. The HasConditionalParams() and PreconditionFailed(...) methods can help with this.

Implementing a conditional read might look like:

huma.Register(api, huma.Operation{
	OperationID: "get-resource",
	Method:      http.MethodGet,
	Path:        "/resource",
	Summary:     "Get a resource",
}, func(ctx context.Context, input struct {
	conditional.Params
}) (*YourOutput, error) {
	if input.HasConditionalParams() {
		// TODO: Get the ETag and last modified time from the resource.
		etag := ""
		modified := time.Time{}

		// If preconditions fail, abort the request processing. Response status
		// codes are already set for you, but you can optionally provide a body.
		// Returns an HTTP 304 not modified.
		if err := input.PreconditionFailed(etag, modified); err != nil {
			return err
		}

		// Otherwise do the normal request processing here...
		// ...
	}
})

🐳 Note that it is more efficient to construct custom DB queries to handle conditional requests, however Huma is not aware of your database. The built-in conditional utilities are designed to be generic and work with any data source, and are a quick and easy way to get started with conditional request handling.

Auto Patch Operations

If a GET and a PUT exist for the same resource, but no PATCH exists at server start up, then a PATCH operation can be generated for you to make editing more convenient for clients. You can opt-in to this behavior with the autopatch package:

import "github.com/danielgtaylor/huma/autopatch"

// ...

// Later in the code *after* registering operations...
autopatch.AutoPatch(api)

If the GET returns an ETag or Last-Modified header, then these will be used to make conditional requests on the PUT operation to prevent distributed write conflicts that might otherwise overwrite someone else's changes.

The following formats are supported out of the box, selected via the Content-Type header:

• JSON Merge Patch application/merge-patch+json
• Shorthand Merge Patch application/merge-patch+shorthand
• JSON Patch application/json-patch+json

If the PATCH request has no Content-Type header, or uses application/json or a variant thereof, then JSON Merge Patch is assumed.

🐳 You can think of the Shorthand Merge Patch as an extension to the JSON merge patch with support for field paths, arrays, and a few other features. Patches like this are possible, appending an item to an array (creating it if needed):

{
  foo.bar[]: "baz",
}

Server Sent Events (SSE)

The sse package provides a helper for streaming Server-Sent Events (SSE) responses. It provides a simple API for sending events to the client and documents the event types and data structures in the OpenAPI spec if you provide a mapping of message type names to Go structs:

// Register using sse.Register instead of huma.Register
sse.Register(api, huma.Operation{
	OperationID: "sse",
	Method:      http.MethodGet,
	Path:        "/sse",
	Summary:     "Server sent events example",
}, map[string]any{
	// Mapping of event type name to Go struct for that event.
	"message":      DefaultMessage{},
	"userCreate":   UserCreatedEvent{},
	"mailRecieved": MailReceivedEvent{},
}, func(ctx context.Context, input *struct{}, send sse.Sender) {
	// Send an event every second for 10 seconds.
	for x := 0; x < 10; x++ {
		send.Data(MailReceivedEvent{UserID: "abc123"})
		time.Sleep(1 * time.Second)
	}
})

🐳 Each event model must be a unique Go type. If you want to reuse Go type definitions, you can define a new type referencing another type, e.g. type MySpecificEvent MyBaseEvent and it will work as expected.

CLI AutoConfig

Huma includes built-in support for an OpenAPI 3 extension that enables CLI autoconfiguration. This allows tools like Restish to automatically configure themselves to talk to your API with the correct endpoints, authentication mechanism, etc without the user needing to know anything about your API.

o := api.OpenAPI()
o.Components.SecuritySchemes["my-scheme"] = &huma.SecurityScheme{
	Type: "oauth2",
	// ... security scheme definition ...
}
o.Extensions["x-cli-autoconfig"] = huma.AutoConfig{
	Security: "my-scheme",
	Params: map[string]string{
		"client_id": "abc123",
		"authorize_url": "https://example.tld/authorize",
		"token_url": "https://example.tld/token",
		"scopes": "read,write",
	}
}

See the CLI AutoConfiguration documentation for more info, including how to ask the user for custom parameters.

Model Validation

Huma includes a utility to make it a little easier to validate models outside of the normal HTTP request/response flow, for example on app startup to load example or default data and verify it is correct. This is just a thin wrapper around the built-in validation functionality, but abstracts away some of the boilerplate required for efficient operation and provides a simple API.

type MyExample struct {
	Name string `json:"name" maxLength:"5"`
	Age int `json:"age" minimum:"25"`
}

var value any
json.Unmarshal([]byte(`{"name": "abcdefg", "age": 1}`), &value)

validator := huma.ModelValidator()
errs := validator.Validate(reflect.TypeOf(MyExample{}), value)
if errs != nil {
	fmt.Println("Validation error", errs)
}

🐳 The huma.ModelValidator is not goroutine-safe! For more flexible validation, use the huma.Validate function directly and provide your own registry, path buffer, validation result struct, etc.

Low-Level API

Huma v2 is written so that you can use the low-level API directly if you want to. This is useful if you want to add some new feature or abstraction that Huma doesn't support out of the box. Huma's own huma.Register function, automatic HTTP PATCH handlers, and the sse package are all built on top of the public low-level API.

huma.Adapter

The adapter is the core of Huma's bring-your-own-router functionality. It is an abstraction on top of routers and HTTP libraries that operates on a generic huma.Context described below. The adapter interface is simple and allows registering operation handlers and serving standard library HTTP requests:

type Adapter interface {
	Handle(op *Operation, handler func(ctx Context))
	ServeHTTP(http.ResponseWriter, *http.Request)
}

huma.Context

The context provides a generic HTTP layer which is translated into specific router operations when called by the adapter.

type Context interface {
	Operation() *Operation
	Context() context.Context
	Method() string
	Host() string
	URL() url.URL
	Param(name string) string
	Query(name string) string
	Header(name string) string
	EachHeader(cb func(name, value string))
	BodyReader() io.Reader
	GetMultipartForm() (*multipart.Form, error)
	SetReadDeadline(time.Time) error
	SetStatus(code int)
	SetHeader(name, value string)
	AppendHeader(name, value string)
	BodyWriter() io.Writer
}

huma.Register

The huma.Register function is a highly-optimized wrapper around the low-level API that handles all the OpenAPI generation, validation, and serialization for you. It is a good example of how to use the low-level API. At a high level it does the following:

1. Adds OpenAPI descriptions of the operation to the OpenAPI spec
2. Registers an operation handler with the adapter
   1. Reads request parameters (ctx.Param, ctx.Query, ctx.Header)
   2. Parses request body if present (ctx.BodyReader)
   3. Calls the user's handler function with all inputs
   4. Handles errors returned from the handler by writing to the ctx
   5. Writes success response (ctx.SetStatus, ctx.SetHeader, ctx.BodyWriter)

🐳 Because huma.Register uses only the public interfaces of the low-level API, you can easily wrap it or write your own register function to provide new functionality.

Migrating from Huma v1

1. Import github.com/danielgtaylor/huma/v2 instead of github.com/danielgtaylor/huma.
2. Use the humachi.NewV4 adapter as Huma v1 uses Chi v4 under the hood
3. Attach your middleware to the chi instance.
4. Replace resource & operation creation with huma.Register
5. Rewrite handlers to be like func(context.Context, *Input) (*Output, error)
   1. Return errors instead of ctx.WriteError(...)
   2. Return instances instead of ctx.WriteModel(...)
6. Define options via a struct and use huma.NewCLI to wrap the service

Note that GraphQL support from Huma v1 has been removed. Take a look at alternative tools like https://www.npmjs.com/package/openapi-to-graphql which will automatically generate a GraphQL endpoint from Huma's generated OpenAPI spec.

Benchmarks

Significant performance improvements have been made since Huma v1, as shown by the following basic benchmark operation with a few input parameters, a small input body, some output headers and an output body (see adapters/humachi/humachi_test.go).

# Huma v1
BenchmarkHumaV1Chi-10         16285  112086 ns/op  852209 B/op  258 allocs/op

# Huma v2
BenchmarkHumaV2ChiNormal-10  431028    2777 ns/op    1718 B/op   29 allocs/op

# Chi without Huma (raw)
BenchmarkRawChi-10           552764    2143 ns/op    2370 B/op   29 allocs/op

These improvements are due to a number of factors, including changes to the Huma API, precomputation of reflection data when possible, low or zero-allocation validation & URL parsing, using shared buffer pools to limit garbage collector pressure, and more.

Since you bring your own router, you are free to "escape" Huma by using the router directly, but as you can see above it's rarely needed with v2.

🐳 Thanks for reading!

Documentation

Overview

Package huma provides a framework for building REST APIs in Go. It is designed to be simple, fast, and easy to use. It is also designed to generate OpenAPI 3.1 specifications and JSON Schema documents describing the API and providing a quick & easy way to generate docs, mocks, SDKs, CLI clients, and more.

https://huma.rocks/

Index

• Constants
• Variables
• func AutoRegister(api API, server any)
• func DefaultSchemaNamer(t reflect.Type, hint string) string
• func FieldSelectTransform(ctx Context, status string, v any) (any, error)
• func Register[I, O any](api API, op Operation, handler func(context.Context, *I) (*O, error))
• func SetReadDeadline(w http.ResponseWriter, deadline time.Time) error
• func Validate(r Registry, s *Schema, path *PathBuffer, mode ValidateMode, v any, ...)
• func WithOptions[Options any](f func(cmd *cobra.Command, args []string, options *Options)) func(*cobra.Command, []string)
• func WriteErr(api API, ctx Context, status int, msg string, errs ...error) error
• type API
  • func NewAPI(config Config, a Adapter) API
• type Adapter
• type AddOpFunc
• type AutoConfig
• type AutoConfigVar
• type CLI
  • func NewCLI[O any](onParsed func(Hooks, *O)) CLI
• type Components
• type Config
  • func DefaultConfig(title, version string) Config
• type Contact
• type ContentTypeFilter
• type Context
• type Encoding
• type ErrorDetail
  • func (e *ErrorDetail) Error() string
  • func (e *ErrorDetail) ErrorDetail() *ErrorDetail
• type ErrorDetailer
• type ErrorModel
  • func (e *ErrorModel) Add(err error)
  • func (e *ErrorModel) ContentType(ct string) string
  • func (e *ErrorModel) Error() string
  • func (e *ErrorModel) GetStatus() int
• type Example
• type ExternalDocs
• type Format
• type Header
• type Hooks
• type Info
• type License
• type Link
• type MediaType
• type Middlewares
  • func (m Middlewares) Handler(endpoint func(Context)) func(Context)
• type ModelValidator
  • func NewModelValidator() *ModelValidator
  • func (v *ModelValidator) Validate(typ reflect.Type, value any) []error
• type OAuthFlow
• type OAuthFlows
• type OpenAPI
  • func (o *OpenAPI) AddOperation(op *Operation)
  • func (o *OpenAPI) MarshalJSON() ([]byte, error)
• type Operation
• type Param
• type PathBuffer
  • func NewPathBuffer(buf []byte, offset int) *PathBuffer
  • func (b *PathBuffer) Bytes() []byte
  • func (b *PathBuffer) Len() int
  • func (b *PathBuffer) Pop()
  • func (b *PathBuffer) Push(s string)
  • func (b *PathBuffer) PushIndex(i int)
  • func (b *PathBuffer) Reset()
  • func (b *PathBuffer) String() string
  • func (b *PathBuffer) With(s string) string
• type PathItem
• type Registry
  • func NewMapRegistry(prefix string, namer func(t reflect.Type, hint string) string) Registry
• type RequestBody
• type Resolver
• type ResolverWithPath
• type Response
• type Schema
  • func SchemaFromField(registry Registry, f reflect.StructField, hint string) *Schema
  • func SchemaFromType(r Registry, t reflect.Type) *Schema
  • func (s *Schema) MarshalJSON() ([]byte, error)
  • func (s *Schema) PrecomputeMessages()
• type SchemaLinkTransformer
  • func NewSchemaLinkTransformer(prefix, schemasPath string) *SchemaLinkTransformer
  • func (t *SchemaLinkTransformer) OnAddOperation(oapi *OpenAPI, op *Operation)
  • func (t *SchemaLinkTransformer) Transform(ctx Context, status string, v any) (any, error)
• type SchemaProvider
• type SecurityScheme
• type Server
• type ServerVariable
• type StatusError
  • func Error400BadRequest(msg string, errs ...error) StatusError
  • func Error401Unauthorized(msg string, errs ...error) StatusError
  • func Error403Forbidden(msg string, errs ...error) StatusError
  • func Error404NotFound(msg string, errs ...error) StatusError
  • func Error405MethodNotAllowed(msg string, errs ...error) StatusError
  • func Error406NotAcceptable(msg string, errs ...error) StatusError
  • func Error409Conflict(msg string, errs ...error) StatusError
  • func Error410Gone(msg string, errs ...error) StatusError
  • func Error412PreconditionFailed(msg string, errs ...error) StatusError
  • func Error415UnsupportedMediaType(msg string, errs ...error) StatusError
  • func Error422UnprocessableEntity(msg string, errs ...error) StatusError
  • func Error429TooManyRequests(msg string, errs ...error) StatusError
  • func Error500InternalServerError(msg string, errs ...error) StatusError
  • func Error501NotImplemented(msg string, errs ...error) StatusError
  • func Error502BadGateway(msg string, errs ...error) StatusError
  • func Error503ServiceUnavailable(msg string, errs ...error) StatusError
  • func Error504GatewayTimeout(msg string, errs ...error) StatusError
  • func Status304NotModified() StatusError
• type StreamResponse
• type Tag
• type Transformer
• type ValidateMode
• type ValidateResult
  • func (r *ValidateResult) Add(path *PathBuffer, v any, msg string)
  • func (r *ValidateResult) Addf(path *PathBuffer, v any, format string, args ...any)
  • func (r *ValidateResult) Reset()

Examples

• Adapter (Handle)
• AutoRegister
• CLI
• ModelValidator
• Resolver

Constants

const (
	TypeBoolean = "boolean"
	TypeInteger = "integer"
	TypeNumber  = "number"
	TypeString  = "string"
	TypeArray   = "array"
	TypeObject  = "object"
)

JSON Schema type constants

Variables

var DefaultCBORFormat = Format{
	Marshal: func(w io.Writer, v any) error {
		return cborEncMode.NewEncoder(w).Encode(v)
	},
	Unmarshal: cbor.Unmarshal,
}

DefaultCBORFormat is the default CBOR formatter that can be set in the API's `Config.Formats` map. This is used by the `DefaultConfig` function.

config := huma.Config{}
config.Formats = map[string]huma.Format{
	"application/cbor": huma.DefaultCBORFormat,
	"cbor":             huma.DefaultCBORFormat,
}

var DefaultJSONFormat = Format{
	Marshal: func(w io.Writer, v any) error {
		return json.NewEncoder(w).Encode(v)
	},
	Unmarshal: json.Unmarshal,
}

DefaultJSONFormat is the default JSON formatter that can be set in the API's `Config.Formats` map. This is used by the `DefaultConfig` function.

config := huma.Config{}
config.Formats = map[string]huma.Format{
	"application/json": huma.DefaultJSONFormat,
	"json":             huma.DefaultJSONFormat,
}

var ErrSchemaInvalid = errors.New("schema is invalid")

ErrSchemaInvalid is sent when there is a problem building the schema.

var NewError = func(status int, msg string, errs ...error) StatusError {
	details := make([]*ErrorDetail, len(errs))
	for i := 0; i < len(errs); i++ {
		if converted, ok := errs[i].(ErrorDetailer); ok {
			details[i] = converted.ErrorDetail()
		} else {
			details[i] = &ErrorDetail{Message: errs[i].Error()}
		}
	}
	return &ErrorModel{
		Status: status,
		Title:  http.StatusText(status),
		Detail: msg,
		Errors: details,
	}
}

NewError creates a new instance of an error model with the given status code, message, and optional error details. If the error details implement the `ErrorDetailer` interface, the error details will be used. Otherwise, the error string will be used as the message. This function is used by all the error response utility functions, like `huma.Error400BadRequest`.

Replace this function to use your own error type. Example:

type MyDetail struct {
	Message string	`json:"message"`
	Location string	`json:"location"`
}

type MyError struct {
	status  int
	Message string	`json:"message"`
	Errors  []error	`json:"errors"`
}

func (e *MyError) Error() string {
	return e.Message
}

func (e *MyError) GetStatus() int {
	return e.status
}

huma.NewError = func(status int, msg string, errs ...error) StatusError {
	return &MyError{
		status:  status,
		Message: msg,
		Errors:  errs,
	}
}

Functions

func AutoRegister

func AutoRegister(api API, server any)

AutoRegister auto-detects operation registration methods and registers them with the given API. Any method named `Register...` will be called and passed the API as the only argument. Since registration happens at service startup, no errors are returned and methods should panic on error.

type ItemsHandler struct {}

func (s *ItemsHandler) RegisterListItems(api API) {
	huma.Register(api, huma.Operation{
		OperationID: "ListItems",
		Method: http.MethodGet,
		Path: "/items",
	}, s.ListItems)
}

func main() {
	router := chi.NewMux()
	config := huma.DefaultConfig("My Service", "1.0.0")
	api := huma.NewExampleAPI(router, config)

	itemsHandler := &ItemsHandler{}
	huma.AutoRegister(api, itemsHandler)
}

Example

package main

import (
	"context"
	"fmt"
	"net/http"

	"github.com/danielgtaylor/huma/v2"
	"github.com/go-chi/chi/v5"
)

// Item represents a single item with a unique ID.
type Item struct {
	ID string `json:"id"`
}

// ItemsResponse is a response containing a list of items.
type ItemsResponse struct {
	Body []Item `json:"body"`
}

// ItemsHandler handles item-related CRUD operations.
type ItemsHandler struct{}

// RegisterListItems registers the `list-items` operation with the given API.
// Because the method starts with `Register` it will be automatically called
// by `huma.AutoRegister` down below.
func (s *ItemsHandler) RegisterListItems(api huma.API) {
	// Register a list operation to get all the items.
	huma.Register(api, huma.Operation{
		OperationID: "list-items",
		Method:      http.MethodGet,
		Path:        "/items",
	}, func(ctx context.Context, input *struct{}) (*ItemsResponse, error) {
		resp := &ItemsResponse{}
		resp.Body = []Item{{ID: "123"}}
		return resp, nil
	})
}

func main() {
	// Create the router and API.
	router := chi.NewMux()
	api := NewExampleAPI(router, huma.DefaultConfig("My Service", "1.0.0"))

	// Create the item handler and register all of its operations.
	itemsHandler := &ItemsHandler{}
	huma.AutoRegister(api, itemsHandler)

	// Confirm the list operation was registered.
	fmt.Println(api.OpenAPI().Paths["/items"].Get.OperationID)
}

Output:

list-items

func DefaultSchemaNamer

func DefaultSchemaNamer(t reflect.Type, hint string) string

DefaultSchemaNamer provides schema names for types. It uses the type name when possible, ignoring the package name. If the type is generic, e.g. `MyType[SubType]`, then the brackets are removed like `MyTypeSubType`. If the type is unnamed, then the name hint is used. Note: if you plan to use types with the same name from different packages, you should implement your own namer function to prevent issues. Nested anonymous types can also present naming issues.

func FieldSelectTransform

func FieldSelectTransform(ctx Context, status string, v any) (any, error)

FieldSelectTransform is an example of a transform that can use an input header value to modify the response on the server, providing a GraphQL-like way to send only the fields that the client wants over the wire.

func Register

func Register[I, O any](api API, op Operation, handler func(context.Context, *I) (*O, error))

Register an operation handler for an API. The handler must be a function that takes a context and a pointer to the input struct and returns a pointer to the output struct and an error. The input struct must be a struct with fields for the request path/query/header parameters and/or body. The output struct must be a struct with fields for the output headers and body of the operation, if any.

huma.Register(api, huma.Operation{
	OperationID: "get-greeting",
	Method:      http.MethodGet,
	Path:        "/greeting/{name}",
	Summary:     "Get a greeting",
}, func(ctx context.Context, input *GreetingInput) (*GreetingOutput, error) {
	if input.Name == "bob" {
		return nil, huma.Error404NotFound("no greeting for bob")
	}
	resp := &GreetingOutput{}
	resp.MyHeader = "MyValue"
	resp.Body.Message = fmt.Sprintf("Hello, %s!", input.Name)
	return resp, nil
})

func SetReadDeadline

func SetReadDeadline(w http.ResponseWriter, deadline time.Time) error

SetReadDeadline is a utility to set the read deadline on a response writer, if possible. If not, it will not incur any allocations (unlike the stdlib `http.ResponseController`). This is mostly a convenience function for adapters so they can be more efficient.

huma.SetReadDeadline(w, time.Now().Add(5*time.Second))

func Validate

func Validate(r Registry, s *Schema, path *PathBuffer, mode ValidateMode, v any, res *ValidateResult)

Validate an input value against a schema, collecting errors in the validation result object. If successful, `res.Errors` will be empty. It is suggested to use a `sync.Pool` to reuse the PathBuffer and ValidateResult objects, making sure to call `Reset()` on them before returning them to the pool.

registry := huma.NewMapRegistry("#/prefix", huma.DefaultSchemaNamer)
schema := huma.SchemaFromType(registry, reflect.TypeOf(MyType{}))
pb := huma.NewPathBuffer([]byte(""), 0)
res := &huma.ValidateResult{}

var value any
json.Unmarshal([]byte(`{"foo": "bar"}`), &v)
huma.Validate(registry, schema, pb, huma.ModeWriteToServer, value, res)
for _, err := range res.Errors {
	fmt.Println(err.Error())
}

func WithOptions

func WithOptions[Options any](f func(cmd *cobra.Command, args []string, options *Options)) func(*cobra.Command, []string)

WithOptions is a helper for custom commands that need to access the options.

cli.Root().AddCommand(&cobra.Command{
	Use: "my-custom-command",
	Run: huma.WithOptions(func(cmd *cobra.Command, args []string, opts *Options) {
		fmt.Println("Hello " + opts.Name)
	}),
})

func WriteErr

func WriteErr(api API, ctx Context, status int, msg string, errs ...error) error

WriteErr writes an error response with the given context, using the configured error type and with the given status code and message. It is marshaled using the API's content negotiation methods.

Types

type API

type API interface {
	// Adapter returns the router adapter for this API, providing a generic
	// interface to get request information and write responses.
	Adapter() Adapter

	// OpenAPI returns the OpenAPI spec for this API. You may edit this spec
	// until the server starts.
	OpenAPI() *OpenAPI

	// Negotiate returns the selected content type given the client's `accept`
	// header and the server's supported content types. If the client does not
	// send an `accept` header, then JSON is used.
	Negotiate(accept string) (string, error)

	// Transform runs the API transformers on the given value. The `status` is
	// the key in the operation's `Responses` map that corresponds to the
	// response being sent (e.g. "200" for a 200 OK response).
	Transform(ctx Context, status string, v any) (any, error)

	// Marshal marshals the given value into the given writer. The
	// content type is used to determine which format to use. Use `Negotiate` to
	// get the content type from an accept header.
	Marshal(w io.Writer, contentType string, v any) error

	// Unmarshal unmarshals the given data into the given value. The content type
	Unmarshal(contentType string, data []byte, v any) error

	// UseMiddleware appends a middleware handler to the API middleware stack.
	//
	// The middleware stack for any API will execute before searching for a matching
	// route to a specific handler, which provides opportunity to respond early,
	// change the course of the request execution, or set request-scoped values for
	// the next Middleware.
	UseMiddleware(middlewares ...func(ctx Context, next func(Context)))

	// Middlewares returns a slice of middleware handler functions.
	Middlewares() Middlewares
}

API represents a Huma API wrapping a specific router.

func NewAPI

func NewAPI(config Config, a Adapter) API

NewAPI creates a new API with the given configuration and router adapter. You usually don't need to use this function directly, and can instead use the `New(...)` function provided by the adapter packages which call this function internally.

When the API is created, this function will ensure a schema registry exists (or create a new map registry if not), will set a default format if not set, and will set up the handlers for the OpenAPI spec, documentation, and JSON schema routes if the paths are set in the config.

router := chi.NewMux()
adapter := humachi.NewAdapter(router)
config := huma.DefaultConfig("Example API", "1.0.0")
api := huma.NewAPI(config, adapter)

type Adapter

type Adapter interface {
	Handle(op *Operation, handler func(ctx Context))
	ServeHTTP(http.ResponseWriter, *http.Request)
}

Adapter is an interface that allows the API to be used with different HTTP routers and frameworks. It is designed to work with the standard library `http.Request` and `http.ResponseWriter` types as well as types like `gin.Context` or `fiber.Ctx` that provide both request and response functionality in one place, by using the `huma.Context` interface which abstracts away those router-specific differences.

The handler function takes uses the context to get request information like path / query / header params, the input body, and provide response data like a status code, response headers, and a response body.

Example (Handle)

ExampleAdapter_handle demonstrates how to use the adapter directly instead of using the `huma.Register` convenience function to add a new operation and handler to the API.

Note that you are responsible for defining all of the operation details, including the parameter and response definitions & schemas.

// Create an adapter for your chosen router.
adapter := NewExampleAdapter(chi.NewMux())

// Register an operation with a custom handler.
adapter.Handle(&huma.Operation{
	OperationID: "example-operation",
	Method:      "GET",
	Path:        "/example/{name}",
	Summary:     "Example operation",
	Parameters: []*huma.Param{
		{
			Name:        "name",
			In:          "path",
			Description: "Name to return",
			Required:    true,
			Schema: &huma.Schema{
				Type: "string",
			},
		},
	},
	Responses: map[string]*huma.Response{
		"200": {
			Description: "OK",
			Content: map[string]*huma.MediaType{
				"text/plain": {
					Schema: &huma.Schema{
						Type: "string",
					},
				},
			},
		},
	},
}, func(ctx huma.Context) {
	// Get the `name` path parameter.
	name := ctx.Param("name")

	// Set the response content type, status code, and body.
	ctx.SetHeader("Content-Type", "text/plain; charset=utf-8")
	ctx.SetStatus(http.StatusOK)
	ctx.BodyWriter().Write([]byte("Hello, " + name))
})

type AddOpFunc

type AddOpFunc func(oapi *OpenAPI, op *Operation)

type AutoConfig

type AutoConfig struct {
	Security string                   `json:"security"`
	Headers  map[string]string        `json:"headers,omitempty"`
	Prompt   map[string]AutoConfigVar `json:"prompt,omitempty"`
	Params   map[string]string        `json:"params"`
}

AutoConfig holds an API's automatic configuration settings for the CLI. These are advertised via OpenAPI extension and picked up by the CLI to make it easier to get started using an API. This struct should be put into the `OpenAPI.Extensions` map under the key `x-cli-config`. See also: https://rest.sh/#/openapi?id=autoconfiguration

type AutoConfigVar

type AutoConfigVar struct {
	Description string        `json:"description,omitempty"`
	Example     string        `json:"example,omitempty"`
	Default     interface{}   `json:"default,omitempty"`
	Enum        []interface{} `json:"enum,omitempty"`

	// Exclude the value from being sent to the server. This essentially makes
	// it a value which is only used in param templates.
	Exclude bool `json:"exclude,omitempty"`
}

AutoConfigVar represents a variable given by the user when prompted during auto-configuration setup of an API.

type CLI

type CLI interface {
	// Run the CLI. This will parse the command-line arguments and environment
	// variables and then run the appropriate command. If no command is given,
	// the default command will call the `OnStart` function to start a server.
	Run()

	// Root returns the root Cobra command. This can be used to add additional
	// commands or flags. Customize it however you like.
	Root() *cobra.Command
}

CLI is an optional command-line interface for a Huma service. It is provided as a convenience for quickly building a service with configuration from the environment and/or command-line options, all tied to a simple type-safe Go struct.

Example

// First, define your input options.
type Options struct {
	Debug bool   `doc:"Enable debug logging"`
	Host  string `doc:"Hostname to listen on."`
	Port  int    `doc:"Port to listen on." short:"p" default:"8888"`
}

// Then, create the CLI.
cli := huma.NewCLI(func(hooks huma.Hooks, opts *Options) {
	fmt.Printf("Options are debug:%v host:%v port%v\n",
		opts.Debug, opts.Host, opts.Port)

	// Set up the router & API
	router := chi.NewRouter()
	api := humachi.New(router, huma.DefaultConfig("My API", "1.0.0"))

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

	srv := &http.Server{
		Addr:    fmt.Sprintf("%s:%d", opts.Host, opts.Port),
		Handler: router,
		// TODO: Set up timeouts!
	}

	hooks.OnStart(func() {
		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
			log.Fatalf("listen: %s\n", err)
		}
	})

	hooks.OnStop(func() {
		srv.Shutdown(context.Background())
	})
})

// Run the thing!
cli.Run()

func NewCLI

func NewCLI[O any](onParsed func(Hooks, *O)) CLI

NewCLI creates a new CLI. The `onParsed` callback is called after the command options have been parsed and the options struct has been populated. You should set up a `hooks.OnStart` callback to start the server with your chosen router.

// First, define your input options.
type Options struct {
	Debug bool   `doc:"Enable debug logging"`
	Host  string `doc:"Hostname to listen on."`
	Port  int    `doc:"Port to listen on." short:"p" default:"8888"`
}

// Then, create the CLI.
cli := huma.NewCLI(func(hooks huma.Hooks, opts *Options) {
	fmt.Printf("Options are debug:%v host:%v port%v\n",
		opts.Debug, opts.Host, opts.Port)

	// Set up the router & API
	router := chi.NewRouter()
	api := humachi.New(router, huma.DefaultConfig("My API", "1.0.0"))
	srv := &http.Server{
		Addr: fmt.Sprintf("%s:%d", opts.Host, opts.Port),
		Handler: router,
		// TODO: Set up timeouts!
	}

	hooks.OnStart(func() {
		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
			log.Fatalf("listen: %s\n", err)
		}
	})

	hooks.OnStop(func() {
		srv.Shutdown(context.Background())
	})
})

// Run the thing!
cli.Run()

type Components

type Components struct {
	// Schemas is an object to hold reusable Schema Objects.
	Schemas Registry `yaml:"schemas,omitempty"`

	// Responses is an object to hold reusable Response Objects.
	Responses map[string]*Response `yaml:"responses,omitempty"`

	// Parameters is an object to hold reusable Parameter Objects.
	Parameters map[string]*Param `yaml:"parameters,omitempty"`

	// Examples is an object to hold reusable Example Objects.
	Examples map[string]*Example `yaml:"examples,omitempty"`

	// RequestBodies is an object to hold reusable Request Body Objects.
	RequestBodies map[string]*RequestBody `yaml:"requestBodies,omitempty"`

	// Headers is an object to hold reusable Header Objects.
	Headers map[string]*Header `yaml:"headers,omitempty"`

	// SecuritySchemes is an object to hold reusable Security Scheme Objects.
	SecuritySchemes map[string]*SecurityScheme `yaml:"securitySchemes,omitempty"`

	// Links is an object to hold reusable Link Objects.
	Links map[string]*Link `yaml:"links,omitempty"`

	// Callbacks is an object to hold reusable Callback Objects.
	Callbacks map[string]*PathItem `yaml:"callbacks,omitempty"`

	// PathItems is an object to hold reusable Path Item Objects.
	PathItems map[string]*PathItem `yaml:"pathItems,omitempty"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

Components holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.

components:
  schemas:
    GeneralError:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
  parameters:
    skipParam:
      name: skip
      in: query
      description: number of items to skip
      required: true
      schema:
        type: integer
        format: int32
    limitParam:
      name: limit
      in: query
      description: max records to return
      required: true
      schema:
        type: integer
        format: int32
  responses:
    NotFound:
      description: Entity not found.
    IllegalInput:
      description: Illegal input for operation.
    GeneralError:
      description: General Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: header
    petstore_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://example.org/api/oauth/dialog
          scopes:
            write:pets: modify pets in your account
            read:pets: read your pets

type Config

type Config struct {
	// OpenAPI spec for the API. You should set at least the `Info.Title` and
	// `Info.Version` fields.
	*OpenAPI

	// OpenAPIPath is the path to the OpenAPI spec without extension. If set
	// to `/openapi` it will allow clients to get `/openapi.json` or
	// `/openapi.yaml`, for example.
	OpenAPIPath string

	// DocsPath is the path to the API documentation. If set to `/docs` it will
	// allow clients to get `/docs` to view the documentation in a browser. If
	// you wish to provide your own documentation renderer, you can leave this
	// blank and attach it directly to the router or adapter.
	DocsPath string

	// SchemasPath is the path to the API schemas. If set to `/schemas` it will
	// allow clients to get `/schemas/{schema}` to view the schema in a browser
	// or for use in editors like VSCode to provide autocomplete & validation.
	SchemasPath string

	// Formats defines the supported request/response formats by content type or
	// extension (e.g. `json` for `application/my-format+json`).
	Formats map[string]Format

	// DefaultFormat specifies the default content type to use when the client
	// does not specify one. If unset, the default type will be randomly
	// chosen from the keys of `Formats`.
	DefaultFormat string

	// Transformers are a way to modify a response body before it is serialized.
	Transformers []Transformer
}

Config represents a configuration for a new API. See `huma.DefaultConfig()` as a starting point.

func DefaultConfig

func DefaultConfig(title, version string) Config

DefaultConfig returns a default configuration for a new API. It is a good starting point for creating your own configuration. It supports JSON and CBOR formats out of the box. The registry uses references for structs and a link transformer is included to add `$schema` fields and links into responses. The `/openapi.[json|yaml]`, `/docs`, and `/schemas` paths are set up to serve the OpenAPI spec, docs UI, and schemas respectively.

// Create and customize the config (if desired).
config := huma.DefaultConfig("My API", "1.0.0")

// Create the API using the config.
router := chi.NewMux()
api := humachi.New(router, config)

type Contact

type Contact struct {
	// Name of the contact person/organization.
	Name string `yaml:"name,omitempty"`

	// URL pointing to the contact information.
	URL string `yaml:"url,omitempty"`

	// Email address of the contact person/organization.
	Email string `yaml:"email,omitempty"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

Contact information to get support for the API.

name: API Support
url: https://www.example.com/support
email: support@example.com

type ContentTypeFilter

type ContentTypeFilter interface {
	ContentType(string) string
}

ContentTypeFilter allows you to override the content type for responses, allowing you to return a different content type like `application/problem+json` after using the `application/json` marshaller. This should be implemented by the response body struct.

type Context

type Context interface {
	// Operation returns the OpenAPI operation that matched the request.
	Operation() *Operation

	// Context returns the underlying request context.
	Context() context.Context

	// Method returns the HTTP method for the request.
	Method() string

	// Host returns the HTTP host for the request.
	Host() string

	// URL returns the full URL for the request.
	URL() url.URL

	// Param returns the value for the given path parameter.
	Param(name string) string

	// Query returns the value for the given query parameter.
	Query(name string) string

	// Header returns the value for the given header.
	Header(name string) string

	// EachHeader iterates over all headers and calls the given callback with
	// the header name and value.
	EachHeader(cb func(name, value string))

	// BodyReader returns the request body reader.
	BodyReader() io.Reader

	// GetMultipartForm returns the parsed multipart form, if any.
	GetMultipartForm() (*multipart.Form, error)

	// SetReadDeadline sets the read deadline for the request body.
	SetReadDeadline(time.Time) error

	// SetStatus sets the HTTP status code for the response.
	SetStatus(code int)

	// SetHeader sets the given header to the given value, overwriting any
	// existing value. Use `AppendHeader` to append a value instead.
	SetHeader(name, value string)

	// AppendHeader appends the given value to the given header.
	AppendHeader(name, value string)

	// BodyWriter returns the response body writer.
	BodyWriter() io.Writer
}

Context is the current request/response context. It provides a generic interface to get request information and write responses.

type Encoding

type Encoding struct {
	// ContentType for encoding a specific property. Default value depends on the
	// property type: for object - application/json; for array – the default is
	// defined based on the inner type; for all other cases the default is
	// application/octet-stream. The value can be a specific media type (e.g.
	// application/json), a wildcard media type (e.g. image/*), or a
	// comma-separated list of the two types.
	ContentType string `yaml:"contentType,omitempty"`

	// Headers is a map allowing additional information to be provided as headers,
	// for example Content-Disposition. Content-Type is described separately and
	// SHALL be ignored in this section. This property SHALL be ignored if the
	// request body media type is not a multipart.
	Headers map[string]*Header `yaml:"headers,omitempty"`

	// Style describes how a specific property value will be serialized depending
	// on its type. See Parameter Object for details on the style property. The
	// behavior follows the same values as query parameters, including default
	// values. This property SHALL be ignored if the request body media type is
	// not application/x-www-form-urlencoded or multipart/form-data. If a value is
	// explicitly defined, then the value of contentType (implicit or explicit)
	// SHALL be ignored.
	Style string `yaml:"style,omitempty"`

	// Explode, when true, property values of type array or object generate
	// separate parameters for each value of the array, or key-value-pair of the
	// map. For other types of properties this property has no effect. When style
	// is form, the default value is true. For all other styles, the default value
	// is false. This property SHALL be ignored if the request body media type is
	// not application/x-www-form-urlencoded or multipart/form-data. If a value is
	// explicitly defined, then the value of contentType (implicit or explicit)
	// SHALL be ignored.
	Explode *bool `yaml:"explode,omitempty"`

	// AllowReserved determines whether the parameter value SHOULD allow reserved
	// characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included
	// without percent-encoding. The default value is false. This property SHALL
	// be ignored if the request body media type is not
	// application/x-www-form-urlencoded or multipart/form-data. If a value is
	// explicitly defined, then the value of contentType (implicit or explicit)
	// SHALL be ignored.
	AllowReserved bool `yaml:"allowReserved,omitempty"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

Encoding is a single encoding definition applied to a single schema property.

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            # default is text/plain
            type: string
            format: uuid
          address:
            # default is application/json
            type: object
            properties: {}
          historyMetadata:
            # need to declare XML format!
            description: metadata in XML format
            type: object
            properties: {}
          profileImage: {}
      encoding:
        historyMetadata:
          # require XML Content-Type in utf-8 encoding
          contentType: application/xml; charset=utf-8
        profileImage:
          # only accept png/jpeg
          contentType: image/png, image/jpeg
          headers:
            X-Rate-Limit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer

type ErrorDetail

type ErrorDetail struct {
	// Message is a human-readable explanation of the error.
	Message string `json:"message,omitempty" doc:"Error message text"`

	// Location is a path-like string indicating where the error occurred.
	// It typically begins with `path`, `query`, `header`, or `body`. Example:
	// `body.items[3].tags` or `path.thing-id`.
	Location string `json:"location,omitempty" doc:"Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'"`

	// Value is the value at the given location, echoed back to the client
	// to help with debugging. This can be useful for e.g. validating that
	// the client didn't send extra whitespace or help when the client
	// did not log an outgoing request.
	Value any `json:"value,omitempty" doc:"The value at the given location"`
}

ErrorDetail provides details about a specific error.

func (*ErrorDetail) Error

func (e *ErrorDetail) Error() string

Error returns the error message / satisfies the `error` interface. If a location and value are set, they will be included in the error message, otherwise just the message is returned.

func (*ErrorDetail) ErrorDetail

func (e *ErrorDetail) ErrorDetail() *ErrorDetail

ErrorDetail satisfies the `ErrorDetailer` interface.

type ErrorDetailer

type ErrorDetailer interface {
	ErrorDetail() *ErrorDetail
}

ErrorDetailer returns error details for responses & debugging. This enables the use of custom error types. See `NewError` for more details.

type ErrorModel

type ErrorModel struct {
	// Type is a URI to get more information about the error type.
	Type string `` /* 170-byte string literal not displayed */

	// Title provides a short static summary of the problem. Huma will default this
	// to the HTTP response status code text if not present.
	Title string `` /* 166-byte string literal not displayed */

	// Status provides the HTTP status code for client convenience. Huma will
	// default this to the response status code if unset. This SHOULD match the
	// response status code (though proxies may modify the actual status code).
	Status int `json:"status,omitempty" example:"400" doc:"HTTP status code"`

	// Detail is an explanation specific to this error occurrence.
	Detail string `` /* 153-byte string literal not displayed */

	// Instance is a URI to get more info about this error occurrence.
	Instance string `` /* 163-byte string literal not displayed */

	// Errors provides an optional mechanism of passing additional error details
	// as a list.
	Errors []*ErrorDetail `json:"errors,omitempty" doc:"Optional list of individual error details"`
}

ErrorModel defines a basic error message model based on RFC 7807 Problem Details for HTTP APIs (https://datatracker.ietf.org/doc/html/rfc7807). It is augmented with an `errors` field of `huma.ErrorDetail` objects that can help provide exhaustive & descriptive errors.

err := &huma.ErrorModel{
	Title: http.StatusText(http.StatusBadRequest),
	Status http.StatusBadRequest,
	Detail: "Validation failed",
	Errors: []*huma.ErrorDetail{
		&huma.ErrorDetail{
			Message: "expected required property id to be present",
			Location: "body.friends[0]",
			Value: nil,
		},
		&huma.ErrorDetail{
			Message: "expected boolean",
			Location: "body.friends[1].active",
			Value: 5,
		},
	},
}

func (*ErrorModel) Add

func (e *ErrorModel) Add(err error)

Add an error to the `Errors` slice. If passed a struct that satisfies the `huma.ErrorDetailer` interface, then it is used, otherwise the error string is used as the error detail message.

err := &ErrorModel{ /* ... */ }
err.Add(&huma.ErrorDetail{
	Message: "expected boolean",
	Location: "body.friends[1].active",
	Value: 5
})

func (*ErrorModel) ContentType

func (e *ErrorModel) ContentType(ct string) string

ContentType provides a filter to adjust response content types. This is used to ensure e.g. `application/problem+json` content types defined in RFC 7807 Problem Details for HTTP APIs are used in responses to clients.

func (*ErrorModel) Error

func (e *ErrorModel) Error() string

Error satisfies the `error` interface. It returns the error's detail field.

func (*ErrorModel) GetStatus

func (e *ErrorModel) GetStatus() int

GetStatus returns the HTTP status that should be returned to the client for this error.

type Example

type Example struct {
	// Ref is a reference to another example. This field is mutually exclusive
	// with the other fields.
	Ref string `yaml:"$ref,omitempty"`

	// Summary is a short summary of the example.
	Summary string `yaml:"summary,omitempty"`

	// Description is a long description of the example. CommonMark syntax MAY
	// be used for rich text representation.
	Description string `yaml:"description,omitempty"`

	// Value is an embedded literal example. The `value` field and `externalValue`
	// field are mutually exclusive. To represent examples of media types that
	// cannot naturally represented in JSON or YAML, use a string value to contain
	// the example, escaping where necessary.
	Value any `yaml:"value,omitempty"`

	// ExternalValue is a URI that points to the literal example. This provides
	// the capability to reference examples that cannot easily be included in JSON
	// or YAML documents. The `value` field and `externalValue` field are mutually
	// exclusive. See the rules for resolving Relative References.
	ExternalValue string `yaml:"externalValue,omitempty"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

Example value of a request param or body or response header or body.

requestBody:
  content:
    'application/json':
      schema:
        $ref: '#/components/schemas/Address'
      examples:
        foo:
          summary: A foo example
          value: {"foo": "bar"}
        bar:
          summary: A bar example
          value: {"bar": "baz"}

type ExternalDocs

type ExternalDocs struct {
	// Description of the target documentation. CommonMark syntax MAY be used for
	// rich text representation.
	Description string `yaml:"description,omitempty"`

	// URL is REQUIRED. The URL for the target documentation. Value MUST be in the
	// format of a URL.
	URL string `yaml:"url"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

ExternalDocs allows referencing an external resource for extended documentation.

description: Find more info here
url: https://example.com

type Format

type Format struct {
	// Marshal a value to a given writer (e.g. response body).
	Marshal func(writer io.Writer, v any) error

	// Unmarshal a value into `v` from the given bytes (e.g. request body).
	Unmarshal func(data []byte, v any) error
}

Format represents a request / response format. It is used to marshal and unmarshal data.

type Header

type Header = Param

Header object follows the structure of the Parameter Object with the following changes:

• name MUST NOT be specified, it is given in the corresponding headers map.

• in MUST NOT be specified, it is implicitly in header.

• All traits that are affected by the location MUST be applicable to a location of header (for example, style).

Example:

description: The number of allowed requests in the current period
schema:
  type: integer

type Hooks

type Hooks interface {
	// OnStart sets a function to call when the service should be started. This
	// is called by the default command if no command is given. The callback
	// should take whatever steps are necessary to start the server, such as
	// `httpServer.ListenAndServer(...)`.
	OnStart(func())

	// OnStop sets a function to call when the service should be stopped. This
	// is called by the default command if no command is given. The callback
	// should take whatever steps are necessary to stop the server, such as
	// `httpServer.Shutdown(...)`.
	OnStop(func())
}

Hooks is an interface for setting up callbacks for the CLI. It is used to start and stop the service.

type Info

type Info struct {
	// Title of the API.
	Title string `yaml:"title"`

	// Description of the API. CommonMark syntax MAY be used for rich text representation.
	Description string `yaml:"description,omitempty"`

	// TermsOfService URL for the API.
	TermsOfService string `yaml:"termsOfService,omitempty"`

	// Contact information to get support for the API.
	Contact *Contact `yaml:"contact,omitempty"`

	// License name & link for using the API.
	License *License `yaml:"license,omitempty"`

	// Version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).
	Version string `yaml:"version"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

Info object that provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience.

title: Sample Pet Store App
summary: A pet store manager.
description: This is a sample server for a pet store.
termsOfService: https://example.com/terms/
contact:
  name: API Support
  url: https://www.example.com/support
  email: support@example.com
license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1

type License

type License struct {
	// Name of the license.
	Name string `yaml:"name"`

	// Identifier SPDX license expression for the API. This field is mutually
	// exclusive with the URL field.
	Identifier string `yaml:"identifier,omitempty"`

	// URL pointing to the license. This field is mutually exclusive with the
	// Identifier field.
	URL string `yaml:"url,omitempty"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

License name & link for using the API.

name: Apache 2.0
identifier: Apache-2.0

type Link

type Link struct {
	// Ref is a reference to another example. This field is mutually exclusive
	// with the other fields.
	Ref string `yaml:"$ref,omitempty"`

	// OperationRef is a relative or absolute URI reference to an OAS operation.
	// This field is mutually exclusive of the operationId field, and MUST point
	// to an Operation Object. Relative operationRef values MAY be used to locate
	// an existing Operation Object in the OpenAPI definition. See the rules for
	// resolving Relative References.
	OperationRef string `yaml:"operationRef,omitempty"`

	// OperationID is the name of an existing, resolvable OAS operation, as
	// defined with a unique operationId. This field is mutually exclusive of the
	// operationRef field.
	OperationID string `yaml:"operationId,omitempty"`

	// Parameters is a map representing parameters to pass to an operation as
	// specified with operationId or identified via operationRef. The key is the
	// parameter name to be used, whereas the value can be a constant or an
	// expression to be evaluated and passed to the linked operation. The
	// parameter name can be qualified using the parameter location [{in}.]{name}
	// for operations that use the same parameter name in different locations
	// (e.g. path.id).
	Parameters map[string]any `yaml:"parameters,omitempty"`

	// RequestBody is a literal value or {expression} to use as a request body
	// when calling the target operation.
	RequestBody any `yaml:"requestBody,omitempty"`

	// Description of the link. CommonMark syntax MAY be used for rich text representation.
	Description string `yaml:"description,omitempty"`

	// Server object to be used by the target operation.
	Server *Server `yaml:"server,omitempty"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

Link object represents a possible design-time link for a response. The presence of a link does not guarantee the caller’s ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations.

Unlike dynamic links (i.e. links provided in the response payload), the OAS linking mechanism does not require link information in the runtime response.

For computing links, and providing instructions to execute them, a runtime expression is used for accessing values in an operation and using them as parameters while invoking the linked operation.

paths:
  /users/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: the user identifier, as userId
      schema:
        type: string
    get:
      responses:
        '200':
          description: the user being returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid: # the unique user id
                    type: string
                    format: uuid
          links:
            address:
              # the target link operationId
              operationId: getUserAddress
              parameters:
                # get the `id` field from the request path parameter named `id`
                userId: $request.path.id
  # the path item of the linked operation
  /users/{userid}/address:
    parameters:
    - name: userid
      in: path
      required: true
      description: the user identifier, as userId
      schema:
        type: string
    # linked operation
    get:
      operationId: getUserAddress
      responses:
        '200':
          description: the user's address

type MediaType

type MediaType struct {
	// Schema defining the content of the request, response, or parameter.
	Schema *Schema `yaml:"schema,omitempty"`

	// Example of the media type. The example object SHOULD be in the correct
	// format as specified by the media type. The example field is mutually
	// exclusive of the examples field. Furthermore, if referencing a schema which
	// contains an example, the example value SHALL override the example provided
	// by the schema.
	Example any `yaml:"example,omitempty"`

	// Examples of the media type. Each example object SHOULD match the media type
	// and specified schema if present. The examples field is mutually exclusive
	// of the example field. Furthermore, if referencing a schema which contains
	// an example, the examples value SHALL override the example provided by the
	// schema.
	Examples map[string]*Example `yaml:"examples,omitempty"`

	// Encoding is a map between a property name and its encoding information. The
	// key, being the property name, MUST exist in the schema as a property. The
	// encoding object SHALL only apply to requestBody objects when the media type
	// is multipart or application/x-www-form-urlencoded.
	Encoding map[string]*Encoding `yaml:"encoding,omitempty"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

MediaType object provides schema and examples for the media type identified by its key.

application/json:
  schema:
    $ref: "#/components/schemas/Pet"
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian

type Middlewares

type Middlewares []func(ctx Context, next func(Context))

Middlewares is a list of middleware functions that can be attached to an API and will be called for all incoming requests.

func (Middlewares) Handler

func (m Middlewares) Handler(endpoint func(Context)) func(Context)

Handler builds and returns a handler func from the chain of middlewares, with `endpoint func` as the final handler.

type ModelValidator

type ModelValidator struct {
	// contains filtered or unexported fields
}

ModelValidator is a utility for validating e.g. JSON loaded data against a Go struct model. It is not goroutine-safe and should not be used in HTTP handlers! Schemas are generated on-the-fly on first use and re-used on subsequent calls. This utility can be used to easily validate data outside of the normal request/response flow, for example on application startup:

type MyExample struct {
	Name string `json:"name" maxLength:"5"`
	Age int `json:"age" minimum:"25"`
}

var value any
json.Unmarshal([]byte(`{"name": "abcdefg", "age": 1}`), &value)

validator := ModelValidator()
errs := validator.Validate(reflect.TypeOf(MyExample{}), value)
if errs != nil {
	fmt.Println("Validation error", errs)
}

Example

// Define a type you want to validate.
type Model struct {
	Name string `json:"name" maxLength:"5"`
	Age  int    `json:"age" minimum:"25"`
}

typ := reflect.TypeOf(Model{})

// Unmarshal some JSON into an `any` for validation. This input should not
// validate against the schema for the struct above.
var val any
json.Unmarshal([]byte(`{"name": "abcdefg", "age": 1}`), &val)

// Validate the unmarshaled data against the type and print errors.
validator := huma.NewModelValidator()
errs := validator.Validate(typ, val)
fmt.Println(errs)

// Try again with valid data!
json.Unmarshal([]byte(`{"name": "foo", "age": 25}`), &val)
errs = validator.Validate(typ, val)
fmt.Println(errs)

Output:

[expected length <= 5 (name: abcdefg) expected number >= 25 (age: 1)]
[]

func NewModelValidator

func NewModelValidator() *ModelValidator

NewModelValidator creates a new model validator with all the components it needs to create schemas, validate them, and return any errors.

func (*ModelValidator) Validate

func (v *ModelValidator) Validate(typ reflect.Type, value any) []error

Validate the inputs. The type should be the Go struct with validation field tags and the value should be e.g. JSON loaded into an `any`. A list of errors is returned if validation failed, otherwise `nil`.

type MyExample struct {
	Name string `json:"name" maxLength:"5"`
	Age int `json:"age" minimum:"25"`
}

var value any
json.Unmarshal([]byte(`{"name": "abcdefg", "age": 1}`), &value)

validator := ModelValidator()
errs := validator.Validate(reflect.TypeOf(MyExample{}), value)
if errs != nil {
	fmt.Println("Validation error", errs)
}

type OAuthFlow

type OAuthFlow struct {
	// AuthorizationURL is REQUIRED. The authorization URL to be used for this
	// flow. This MUST be in the form of a URL. The OAuth2 standard requires the
	// use of TLS.
	AuthorizationURL string `yaml:"authorizationUrl"`

	// TokenURL is REQUIRED. The token URL to be used for this flow. This MUST be
	// in the form of a URL. The OAuth2 standard requires the use of TLS.
	TokenURL string `yaml:"tokenUrl"`

	// RefreshURL is the URL to be used for obtaining refresh tokens. This MUST be
	// in the form of a URL. The OAuth2 standard requires the use of TLS.
	RefreshURL string `yaml:"refreshUrl,omitempty"`

	// Scopes are REQUIRED. The available scopes for the OAuth2 security scheme. A
	// map between the scope name and a short description for it. The map MAY be
	// empty.
	Scopes map[string]string `yaml:"scopes"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

OAuthFlow stores configuration details for a supported OAuth Flow.

type: oauth2
flows:
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets
  authorizationCode:
    authorizationUrl: https://example.com/api/oauth/dialog
    tokenUrl: https://example.com/api/oauth/token
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets

type OAuthFlows

type OAuthFlows struct {
	// Implicit is the configuration for the OAuth Implicit flow.
	Implicit *OAuthFlow `yaml:"implicit,omitempty"`

	// Password is the configuration for the OAuth Resource Owner Password flow.
	Password *OAuthFlow `yaml:"password,omitempty"`

	// ClientCredentials is the configuration for the OAuth Client Credentials
	// flow. Previously called application in OpenAPI 2.0.
	ClientCredentials *OAuthFlow `yaml:"clientCredentials,omitempty"`

	// AuthorizationCode is the configuration for the OAuth Authorization Code
	// flow. Previously called accessCode in OpenAPI 2.0.
	AuthorizationCode *OAuthFlow `yaml:"authorizationCode,omitempty"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

OAuthFlows allows configuration of the supported OAuth Flows.

type OpenAPI

type OpenAPI struct {
	// OpenAPI is REQUIRED. This string MUST be the version number of the OpenAPI
	// Specification that the OpenAPI document uses. The openapi field SHOULD be
	// used by tooling to interpret the OpenAPI document. This is not related to
	// the API info.version string.
	OpenAPI string `yaml:"openapi"`

	// Info is REQUIRED. Provides metadata about the API. The metadata MAY be used
	// by tooling as required.
	Info *Info `yaml:"info"`

	// JSONSchemaDialect is he default value for the $schema keyword within Schema
	// Objects contained within this OAS document. This MUST be in the form of a
	// URI.
	JSONSchemaDialect string `yaml:"jsonSchemaDialect,omitempty"`

	// Servers is an array of Server Objects, which provide connectivity
	// information to a target server. If the servers property is not provided, or
	// is an empty array, the default value would be a Server Object with a url
	// value of /.
	Servers []*Server `yaml:"servers,omitempty"`

	// Paths are the available paths and operations for the API.
	Paths map[string]*PathItem `yaml:"paths,omitempty"`

	// Webhooks that MAY be received as part of this API and that the API consumer
	// MAY choose to implement. Closely related to the callbacks feature, this
	// section describes requests initiated other than by an API call, for example
	// by an out of band registration. The key name is a unique string to refer to
	// each webhook, while the (optionally referenced) Path Item Object describes
	// a request that may be initiated by the API provider and the expected
	// responses. An example is available.
	Webhooks map[string]*PathItem `yaml:"webhooks,omitempty"`

	// Components is an element to hold various schemas for the document.
	Components *Components `yaml:"components,omitempty"`

	// Security is a declaration of which security mechanisms can be used across
	// the API. The list of values includes alternative security requirement
	// objects that can be used. Only one of the security requirement objects need
	// to be satisfied to authorize a request. Individual operations can override
	// this definition. To make security optional, an empty security requirement
	// ({}) can be included in the array.
	Security []map[string][]string `yaml:"security,omitempty"`

	// Tags are a list of tags used by the document with additional metadata. The
	// order of the tags can be used to reflect on their order by the parsing
	// tools. Not all tags that are used by the Operation Object must be declared.
	// The tags that are not declared MAY be organized randomly or based on the
	// tools’ logic. Each tag name in the list MUST be unique.
	Tags []*Tag `yaml:"tags,omitempty"`

	// ExternalDocs is additional external documentation.
	ExternalDocs *ExternalDocs `yaml:"externalDocs,omitempty"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`

	// OnAddOperation is called when an operation is added to the OpenAPI via
	// `AddOperation`. You may bypass this by directly writing to the `Paths`
	// map instead.
	OnAddOperation []AddOpFunc `yaml:"-"`
}

OpenAPI is the root object of the OpenAPI document.

func (*OpenAPI) AddOperation

func (o *OpenAPI) AddOperation(op *Operation)

AddOperation adds an operation to the OpenAPI. This is the preferred way to add operations to the OpenAPI, as it will ensure that the operation is properly added to the Paths map, and will call any registered OnAddOperation functions.

func (*OpenAPI) MarshalJSON

func (o *OpenAPI) MarshalJSON() ([]byte, error)

type Operation

type Operation struct {

	// Method is the HTTP method for this operation
	Method string `yaml:"-"`

	// Path is the URL path for this operation
	Path string `yaml:"-"`

	// DefaultStatus is the default HTTP status code for this operation. It will
	// be set to 200 or 204 if not specified, depending on whether the handler
	// returns a response body.
	DefaultStatus int `yaml:"-"`

	// MaxBodyBytes is the maximum number of bytes to read from the request
	// body. If not specified, the default is 1MB. Use -1 for unlimited. If
	// the limit is reached, then an HTTP 413 error is returned.
	MaxBodyBytes int64 `yaml:"-"`

	// BodyReadTimeout is the maximum amount of time to wait for the request
	// body to be read. If not specified, the default is 5 seconds. Use -1
	// for unlimited. If the timeout is reached, then an HTTP 408 error is
	// returned. This value supercedes the server's read timeout, and a value
	// of -1 can unset the server's timeout.
	BodyReadTimeout time.Duration `yaml:"-"`

	// Errors is a list of HTTP status codes that the handler may return. If
	// not specified, then a default error response is added to the OpenAPI.
	// This is a convenience for handlers that return a fixed set of errors
	// where you do not wish to provide each one as an OpenAPI response object.
	// Each error specified here is expanded into a response object with the
	// schema generated from the type returned by `huma.NewError()`.
	Errors []int `yaml:"-"`

	// SkipValidateParams disables validation of path, query, and header
	// parameters. This can speed up request processing if you want to handle
	// your own validation. Use with caution!
	SkipValidateParams bool `yaml:"-"`

	// SkipValidateBody disables validation of the request body. This can speed
	// up request processing if you want to handle your own validation. Use with
	// caution!
	SkipValidateBody bool `yaml:"-"`

	// Hidden will skip documenting this operation in the OpenAPI. This is
	// useful for operations that are not intended to be used by clients but
	// you'd still like the benefits of using Huma. Generally not recommended.
	Hidden bool `yaml:"-"`

	// Metadata is a map of arbitrary data that can be attached to the operation.
	// This can be used to store custom data, such as custom settings for
	// functions which generate operations.
	Metadata map[string]any `yaml:"-"`

	// Tags is a list of tags for API documentation control. Tags can be used for
	// logical grouping of operations by resources or any other qualifier.
	Tags []string `yaml:"tags,omitempty"`

	// Summary is a short summary of what the operation does.
	Summary string `yaml:"summary,omitempty"`

	// Description is a verbose explanation of the operation behavior. CommonMark
	// syntax MAY be used for rich text representation.
	Description string `yaml:"description,omitempty"`

	// ExternalDocs describes additional external documentation for this
	// operation.
	ExternalDocs *ExternalDocs `yaml:"externalDocs,omitempty"`

	// OperationID is a unique string used to identify the operation. The id MUST
	// be unique among all operations described in the API. The operationId value
	// is case-sensitive. Tools and libraries MAY use the operationId to uniquely
	// identify an operation, therefore, it is RECOMMENDED to follow common
	// programming naming conventions.
	OperationID string `yaml:"operationId,omitempty"`

	// Parameters is a list of parameters that are applicable for this operation.
	// If a parameter is already defined at the Path Item, the new definition will
	// override it but can never remove it. The list MUST NOT include duplicated
	// parameters. A unique parameter is defined by a combination of a name and
	// location. The list can use the Reference Object to link to parameters that
	// are defined at the OpenAPI Object’s components/parameters.
	Parameters []*Param `yaml:"parameters,omitempty"`

	// RequestBody applicable for this operation. The requestBody is fully
	// supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has
	// explicitly defined semantics for request bodies. In other cases where the
	// HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted
	// but does not have well-defined semantics and SHOULD be avoided if possible.
	RequestBody *RequestBody `yaml:"requestBody,omitempty"`

	// Responses is the list of possible responses as they are returned from
	// executing this operation.
	Responses map[string]*Response `yaml:"responses,omitempty"`

	// Callbacks is a map of possible out-of band callbacks related to the parent
	// operation. The key is a unique identifier for the Callback Object. Each
	// value in the map is a Callback Object that describes a request that may be
	// initiated by the API provider and the expected responses.
	Callbacks map[string]*PathItem `yaml:"callbacks,omitempty"`

	// Deprecated declares this operation to be deprecated. Consumers SHOULD
	// refrain from usage of the declared operation. Default value is false.
	Deprecated bool `yaml:"deprecated,omitempty"`

	// Security is a declaration of which security mechanisms can be used for this
	// operation. The list of values includes alternative security requirement
	// objects that can be used. Only one of the security requirement objects need
	// to be satisfied to authorize a request. To make security optional, an empty
	// security requirement ({}) can be included in the array. This definition
	// overrides any declared top-level security. To remove a top-level security
	// declaration, an empty array can be used.
	Security []map[string][]string `yaml:"security,omitempty"`

	// Servers is an alternative server array to service this operation. If an
	// alternative server object is specified at the Path Item Object or Root
	// level, it will be overridden by this value.
	Servers []*Server `yaml:"servers,omitempty"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

Operation describes a single API operation on a path.

tags:
- pet
summary: Updates a pet in the store with form data
operationId: updatePetWithForm
parameters:
- name: petId
  in: path
  description: ID of pet that needs to be updated
  required: true
  schema:
    type: string
requestBody:
  content:
    'application/x-www-form-urlencoded':
      schema:
       type: object
       properties:
          name:
            description: Updated name of the pet
            type: string
          status:
            description: Updated status of the pet
            type: string
       required:
         - status
responses:
  '200':
    description: Pet updated.
    content:
      'application/json': {}
      'application/xml': {}
  '405':
    description: Method Not Allowed
    content:
      'application/json': {}
      'application/xml': {}
security:
- petstore_auth:
  - write:pets
  - read:pets

type Param

type Param struct {
	// Ref is a reference to another example. This field is mutually exclusive
	// with the other fields.
	Ref string `yaml:"$ref,omitempty"`

	// Name is REQUIRED. The name of the parameter. Parameter names are case
	// sensitive.
	//
	//   - If in is "path", the name field MUST correspond to a template expression
	//     occurring within the path field in the Paths Object. See Path Templating
	//     for further information.
	//
	//   - If in is "header" and the name field is "Accept", "Content-Type" or
	//     "Authorization", the parameter definition SHALL be ignored.
	//
	//   - For all other cases, the name corresponds to the parameter name used by
	//     the in property.
	Name string `yaml:"name,omitempty"`

	// In is REQUIRED. The location of the parameter. Possible values are "query",
	// "header", "path" or "cookie".
	In string `yaml:"in,omitempty"`

	// Description of the parameter. This could contain examples of use.
	// CommonMark syntax MAY be used for rich text representation.
	Description string `yaml:"description,omitempty"`

	// Required determines whether this parameter is mandatory. If the parameter
	// location is "path", this property is REQUIRED and its value MUST be true.
	// Otherwise, the property MAY be included and its default value is false.
	Required bool `yaml:"required,omitempty"`

	// Deprecated specifies that a parameter is deprecated and SHOULD be
	// transitioned out of usage. Default value is false.
	Deprecated bool `yaml:"deprecated,omitempty"`

	// AllowEmptyValue sets the ability to pass empty-valued parameters. This is
	// valid only for query parameters and allows sending a parameter with an
	// empty value. Default value is false. If style is used, and if behavior is
	// n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored.
	// Use of this property is NOT RECOMMENDED, as it is likely to be removed in a
	// later revision.
	AllowEmptyValue bool `yaml:"allowEmptyValue,omitempty"`

	// Style describes how the parameter value will be serialized depending on the
	// type of the parameter value. Default values (based on value of in): for
	// query - form; for path - simple; for header - simple; for cookie - form.
	Style string `yaml:"style,omitempty"`

	// Explode, when true, makes parameter values of type array or object generate
	// separate parameters for each value of the array or key-value pair of the
	// map. For other types of parameters this property has no effect. When style
	// is form, the default value is true. For all other styles, the default value
	// is false.
	Explode *bool `yaml:"explode,omitempty"`

	// AllowReserved determines whether the parameter value SHOULD allow reserved
	// characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included
	// without percent-encoding. This property only applies to parameters with an
	// in value of query. The default value is false.
	AllowReserved bool `yaml:"allowReserved,omitempty"`

	// Schema defining the type used for the parameter.
	Schema *Schema `yaml:"schema,omitempty"`

	// Example of the parameter’s potential value. The example SHOULD match the
	// specified schema and encoding properties if present. The example field is
	// mutually exclusive of the examples field. Furthermore, if referencing a
	// schema that contains an example, the example value SHALL override the
	// example provided by the schema. To represent examples of media types that
	// cannot naturally be represented in JSON or YAML, a string value can contain
	// the example with escaping where necessary.
	Example any `yaml:"example,omitempty"`

	// Examples of the parameter’s potential value. Each example SHOULD contain a
	// value in the correct format as specified in the parameter encoding. The
	// examples field is mutually exclusive of the example field. Furthermore, if
	// referencing a schema that contains an example, the examples value SHALL
	// override the example provided by the schema.
	Examples map[string]*Example `yaml:"examples,omitempty"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

Param Describes a single operation parameter.

A unique parameter is defined by a combination of a name and location.

name: username
in: path
description: username to fetch
required: true
schema:
  type: string

type PathBuffer

type PathBuffer struct {
	// contains filtered or unexported fields
}

PathBuffer is a low-allocation helper for building a path string like `foo.bar.baz`. It is not goroutine-safe. Combined with `sync.Pool` it can result in zero allocations, and is used for validation. It is significantly better than `strings.Builder` and `bytes.Buffer` for this use case.

Path buffers can be converted to strings for use in responses or printing using either the `pb.String()` or `pb.With("field")` methods.

pb := NewPathBuffer([]byte{}, 0)
pb.Push("foo")  // foo
pb.PushIndex(1) // foo[1]
pb.Push("bar")  // foo[1].bar
pb.Pop()        // foo[1]
pb.Pop()        // foo

func NewPathBuffer

func NewPathBuffer(buf []byte, offset int) *PathBuffer

NewPathBuffer creates a new path buffer given an existing byte slice. Tip: using `sync.Pool` can significantly reduce buffer allocations.

pb := NewPathBuffer([]byte{}, 0)
pb.Push("foo")

func (*PathBuffer) Bytes

func (b *PathBuffer) Bytes() []byte

Bytes returns the underlying slice of bytes of the path.

func (*PathBuffer) Len

func (b *PathBuffer) Len() int

Len returns the length of the current path.

func (*PathBuffer) Pop

func (b *PathBuffer) Pop()

Pop the latest entry off the path.

pb.Push("foo")  // foo
pb.PushIndex(1) // foo[1]
pb.Push("bar")  // foo[1].bar
pb.Pop()        // foo[1]
pb.Pop()        // foo

func (*PathBuffer) Push

func (b *PathBuffer) Push(s string)

Push an entry onto the path, adding a `.` separator as needed.

pb.Push("foo") // foo
pb.Push("bar") // foo.bar

func (*PathBuffer) PushIndex

func (b *PathBuffer) PushIndex(i int)

PushIndex pushes an entry onto the path surrounded by `[` and `]`.

pb.Push("foo")  // foo
pb.PushIndex(1) // foo[1]

func (*PathBuffer) Reset

func (b *PathBuffer) Reset()

Reset the path buffer to empty, keeping and reusing the underlying bytes.

func (*PathBuffer) String

func (b *PathBuffer) String() string

String converts the path buffer to a string.

func (*PathBuffer) With

func (b *PathBuffer) With(s string) string

With is shorthand for push, convert to string, and pop. This is useful when you want the location of a field given a path buffer as a prefix.

pb.Push("foo")
pb.With("bar") // returns foo.bar

type PathItem

type PathItem struct {
	// Ref is a reference to another example. This field is mutually exclusive
	// with the other fields.
	Ref string `yaml:"$ref,omitempty"`

	// Summary is an optional, string summary, intended to apply to all operations
	// in this path.
	Summary string `yaml:"summary,omitempty"`

	// Description is an optional, string description, intended to apply to all
	// operations in this path. CommonMark syntax MAY be used for rich text
	// representation.
	Description string `yaml:"description,omitempty"`

	// Get is a definition of a GET operation on this path.
	Get *Operation `yaml:"get,omitempty"`

	// Put is a definition of a PUT operation on this path.
	Put *Operation `yaml:"put,omitempty"`

	// Post is a definition of a POST operation on this path.
	Post *Operation `yaml:"post,omitempty"`

	// Delete is a definition of a DELETE operation on this path.
	Delete *Operation `yaml:"delete,omitempty"`

	// Options is a definition of a OPTIONS operation on this path.
	Options *Operation `yaml:"options,omitempty"`

	// Head is a definition of a HEAD operation on this path.
	Head *Operation `yaml:"head,omitempty"`

	// Patch is a definition of a PATCH operation on this path.
	Patch *Operation `yaml:"patch,omitempty"`

	// Trace is a definition of a TRACE operation on this path.
	Trace *Operation `yaml:"trace,omitempty"`

	// Servers is an alternative server array to service all operations in this
	// path.
	Servers []*Server `yaml:"servers,omitempty"`

	// Parameters is a list of parameters that are applicable for all the
	// operations described under this path. These parameters can be overridden at
	// the operation level, but cannot be removed there. The list MUST NOT include
	// duplicated parameters. A unique parameter is defined by a combination of a
	// name and location. The list can use the Reference Object to link to
	// parameters that are defined at the OpenAPI Object’s components/parameters.
	Parameters []*Param `yaml:"parameters,omitempty"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

PathItem describes the operations available on a single path. A Path Item MAY be empty, due to ACL constraints. The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.

get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  responses:
    '200':
      description: pet response
      content:
        '*/*' :
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Pet'
    default:
      description: error payload
      content:
        'text/html':
          schema:
            $ref: '#/components/schemas/ErrorModel'
parameters:
- name: id
  in: path
  description: ID of pet to use
  required: true
  schema:
    type: array
    items:
      type: string
  style: simple

type Registry

type Registry interface {
	Schema(t reflect.Type, allowRef bool, hint string) *Schema
	SchemaFromRef(ref string) *Schema
	TypeFromRef(ref string) reflect.Type
	Map() map[string]*Schema
}

Registry creates and stores schemas and their references, and supports marshalling to JSON/YAML for use as an OpenAPI #/components/schemas object. Behavior is implementation-dependent, but the design allows for recursive schemas to exist while being flexible enough to support other use cases like only inline objects (no refs) or always using refs for structs.

func NewMapRegistry

func NewMapRegistry(prefix string, namer func(t reflect.Type, hint string) string) Registry

NewMapRegistry creates a new registry that stores schemas in a map and returns references to them using the given prefix.

type RequestBody

type RequestBody struct {
	// Ref is a reference to another example. This field is mutually exclusive
	// with the other fields.
	Ref string `yaml:"$ref,omitempty"`

	// Description of the request body. This could contain examples of use.
	// CommonMark syntax MAY be used for rich text representation.
	Description string `yaml:"description,omitempty"`

	// Content is REQUIRED. The content of the request body. The key is a media
	// type or media type range and the value describes it. For requests that
	// match multiple keys, only the most specific key is applicable. e.g.
	// text/plain overrides text/*
	Content map[string]*MediaType `yaml:"content"`

	// Required Determines if the request body is required in the request.
	// Defaults to false.
	Required bool `yaml:"required,omitempty"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

RequestBody describes a single request body.

description: user to add to the system
content:
  'application/json':
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User Example
        externalValue: 'https://foo.bar/examples/user-example.json'

type Resolver

type Resolver interface {
	Resolve(ctx Context) []error
}

Resolver runs a `Resolve` function after a request has been parsed, enabling you to run custom validation or other code that can modify the request and / or return errors.

Example

package main

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"net/http/httptest"
	"strings"

	"github.com/danielgtaylor/huma/v2"
	"github.com/go-chi/chi/v5"
)

// Step 1: Create your input struct where you want to do additional validation.
// This struct must implement the `huma.Resolver` interface.
type ExampleInputBody struct {
	Count int `json:"count" minimum:"0"`
}

func (b *ExampleInputBody) Resolve(ctx huma.Context, prefix *huma.PathBuffer) []error {
	// Return an error if some arbitrary rule is broken. In this case, if it's
	// a multiple of 30 we return an error.
	if b.Count%30 == 0 {
		return []error{&huma.ErrorDetail{
			Location: prefix.With("count"),
			Message:  "multiples of 30 are not allowed",
			Value:    b.Count,
		}}
	}

	return nil
}

func main() {
	// Create the API.
	r := chi.NewRouter()
	api := NewExampleAPI(r, huma.DefaultConfig("Example API", "1.0.0"))

	huma.Register(api, huma.Operation{
		OperationID: "resolver-example",
		Method:      http.MethodPut,
		Path:        "/resolver",
	}, func(ctx context.Context, input *struct {
		// Step 2: Use your custom struct with the resolver as a field in the
		// request input. Here we use it as the body of the request.
		Body ExampleInputBody
	}) (*struct{}, error) {
		// Do nothing. Validation should catch the error!
		return nil, nil
	})

	// Make an example request showing the validation error response.
	req, _ := http.NewRequest(http.MethodPut, "/resolver", strings.NewReader(`{"count": 30}`))
	req.Host = "example.com"
	req.Header.Set("Content-Type", "application/json")

	w := httptest.NewRecorder()

	r.ServeHTTP(w, req)

	out := bytes.NewBuffer(nil)
	json.Indent(out, w.Body.Bytes(), "", "  ")
	fmt.Println(out.String())
}

Output:

{
  "$schema": "https://example.com/schemas/ErrorModel.json",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "validation failed",
  "errors": [
    {
      "message": "multiples of 30 are not allowed",
      "location": "body.count",
      "value": 30
    }
  ]
}

type ResolverWithPath

type ResolverWithPath interface {
	Resolve(ctx Context, prefix *PathBuffer) []error
}

ResolverWithPath runs a `Resolve` function after a request has been parsed, enabling you to run custom validation or other code that can modify the request and / or return errors. The `prefix` is the path to the current location for errors, e.g. `body.foo[0].bar`.

type Response

type Response struct {
	// Ref is a reference to another example. This field is mutually exclusive
	// with the other fields.
	Ref string `yaml:"$ref,omitempty"`

	// Description is REQUIRED. A description of the response. CommonMark syntax
	// MAY be used for rich text representation.
	Description string `yaml:"description,omitempty"`

	// Headers maps a header name to its definition. [RFC7230] states header names
	// are case insensitive. If a response header is defined with the name
	// "Content-Type", it SHALL be ignored.
	Headers map[string]*Param `yaml:"headers,omitempty"`

	// Content is a map containing descriptions of potential response payloads.
	// The key is a media type or media type range and the value describes it. For
	// responses that match multiple keys, only the most specific key is
	// applicable. e.g. text/plain overrides text/*
	Content map[string]*MediaType `yaml:"content,omitempty"`

	// Links is a map of operations links that can be followed from the response.
	// The key of the map is a short name for the link, following the naming
	// constraints of the names for Component Objects.
	Links map[string]*Link `yaml:"links,omitempty"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

Response describes a single response from an API Operation, including design-time, static links to operations based on the response.

description: A complex object array response
content:
  application/json:
    schema:
      type: array
      items:
        $ref: '#/components/schemas/VeryComplexType'

type Schema

type Schema struct {
	Type                 string             `yaml:"type,omitempty"`
	Title                string             `yaml:"title,omitempty"`
	Description          string             `yaml:"description,omitempty"`
	Ref                  string             `yaml:"$ref,omitempty"`
	Format               string             `yaml:"format,omitempty"`
	ContentEncoding      string             `yaml:"contentEncoding,omitempty"`
	Default              any                `yaml:"default,omitempty"`
	Examples             []any              `yaml:"examples,omitempty"`
	Items                *Schema            `yaml:"items,omitempty"`
	AdditionalProperties any                `yaml:"additionalProperties,omitempty"`
	Properties           map[string]*Schema `yaml:"properties,omitempty"`
	Enum                 []any              `yaml:"enum,omitempty"`
	Minimum              *float64           `yaml:"minimum,omitempty"`
	ExclusiveMinimum     *float64           `yaml:"exclusiveMinimum,omitempty"`
	Maximum              *float64           `yaml:"maximum,omitempty"`
	ExclusiveMaximum     *float64           `yaml:"exclusiveMaximum,omitempty"`
	MultipleOf           *float64           `yaml:"multipleOf,omitempty"`
	MinLength            *int               `yaml:"minLength,omitempty"`
	MaxLength            *int               `yaml:"maxLength,omitempty"`
	Pattern              string             `yaml:"pattern,omitempty"`
	MinItems             *int               `yaml:"minItems,omitempty"`
	MaxItems             *int               `yaml:"maxItems,omitempty"`
	UniqueItems          bool               `yaml:"uniqueItems,omitempty"`
	Required             []string           `yaml:"required,omitempty"`
	MinProperties        *int               `yaml:"minProperties,omitempty"`
	MaxProperties        *int               `yaml:"maxProperties,omitempty"`
	ReadOnly             bool               `yaml:"readOnly,omitempty"`
	WriteOnly            bool               `yaml:"writeOnly,omitempty"`
	Deprecated           bool               `yaml:"deprecated,omitempty"`
	Extensions           map[string]any     `yaml:",inline"`

	OneOf []*Schema `yaml:"oneOf,omitempty"`
	AnyOf []*Schema `yaml:"anyOf,omitempty"`
	AllOf []*Schema `yaml:"allOf,omitempty"`
	Not   *Schema   `yaml:"not,omitempty"`
	// contains filtered or unexported fields
}

Schema represents a JSON Schema compatible with OpenAPI 3.1. It is extensible with your own custom properties. It supports a subset of the full JSON Schema spec, designed specifically for use with Go structs and to enable fast zero or near-zero allocation happy-path validation for incoming requests.

Typically you will use a registry and `huma.SchemaFromType` to generate schemas for your types. You can then use `huma.Validate` to validate incoming requests.

// Create a registry and register a type.
registry := huma.NewMapRegistry("#/prefix", huma.DefaultSchemaNamer)
schema := huma.SchemaFromType(registry, reflect.TypeOf(MyType{}))

Note that the registry may create references for your types.

func SchemaFromField

func SchemaFromField(registry Registry, f reflect.StructField, hint string) *Schema

SchemaFromField generates a schema for a given struct field. If the field is a struct (or slice/map of structs) then the registry is used to potentially get a reference to that type.

This is used by `huma.SchemaFromType` when it encounters a struct, and is used to generate schemas for path/query/header parameters.

func SchemaFromType

func SchemaFromType(r Registry, t reflect.Type) *Schema

SchemaFromType returns a schema for a given type, using the registry to possibly create references for nested structs. The schema that is returned can then be passed to `huma.Validate` to efficiently validate incoming requests.

// Create a registry and register a type.
registry := huma.NewMapRegistry("#/prefix", huma.DefaultSchemaNamer)
schema := huma.SchemaFromType(registry, reflect.TypeOf(MyType{}))

func (*Schema) MarshalJSON

func (s *Schema) MarshalJSON() ([]byte, error)

MarshalJSON marshals the schema into JSON, respecting the `Extensions` map to marshal extensions inline.

func (*Schema) PrecomputeMessages

func (s *Schema) PrecomputeMessages()

PrecomputeMessages tries to precompute as many validation error messages as possible so that new strings aren't allocated during request validation.

type SchemaLinkTransformer

type SchemaLinkTransformer struct {
	// contains filtered or unexported fields
}

SchemaLinkTransformer is a transform that adds a `$schema` field to the response (if it is a struct) and a Link header pointing to the JSON Schema that describes the response structure. This is useful for clients to understand the structure of the response and enables things like as-you-type validation & completion of HTTP resources in editors like VSCode.

func NewSchemaLinkTransformer

func NewSchemaLinkTransformer(prefix, schemasPath string) *SchemaLinkTransformer

NewSchemaLinkTransformer creates a new transformer that will add a `$schema` field to the response (if it is a struct) and a Link header pointing to the JSON Schema that describes the response structure. This is useful for clients to understand the structure of the response and enables things like as-you-type validation & completion of HTTP resources in editors like VSCode.

func (*SchemaLinkTransformer) OnAddOperation

func (t *SchemaLinkTransformer) OnAddOperation(oapi *OpenAPI, op *Operation)

OnAddOperation is triggered whenever a new operation is added to the API, enabling this transformer to precompute & cache information about the response and schema.

func (*SchemaLinkTransformer) Transform

func (t *SchemaLinkTransformer) Transform(ctx Context, status string, v any) (any, error)

Transform is called for every response to add the `$schema` field and/or the Link header pointing to the JSON Schema.

type SchemaProvider

type SchemaProvider interface {
	Schema(r Registry) *Schema
}

SchemaProvider is an interface that can be implemented by types to provide a custom schema for themselves, overriding the built-in schema generation. This can be used by custom types with their own special serialization rules.

type SecurityScheme

type SecurityScheme struct {
	// Type is REQUIRED. The type of the security scheme. Valid values are
	// "apiKey", "http", "mutualTLS", "oauth2", "openIdConnect".
	Type string `yaml:"type"`

	// Description for security scheme. CommonMark syntax MAY be used for rich
	// text representation.
	Description string `yaml:"description,omitempty"`

	// Name is REQUIRED. The name of the header, query or cookie parameter to be
	// used.
	Name string `yaml:"name,omitempty"`

	// In is REQUIRED. The location of the API key. Valid values are "query",
	// "header" or "cookie".
	In string `yaml:"in,omitempty"`

	// Scheme is REQUIRED. The name of the HTTP Authorization scheme to be used in
	// the Authorization header as defined in [RFC7235]. The values used SHOULD be
	// registered in the IANA Authentication Scheme registry.
	Scheme string `yaml:"scheme,omitempty"`

	// BearerFormat is a hint to the client to identify how the bearer token is
	// formatted. Bearer tokens are usually generated by an authorization server,
	// so this information is primarily for documentation purposes.
	BearerFormat string `yaml:"bearerFormat,omitempty"`

	// Flows is REQUIRED. An object containing configuration information for the
	// flow types supported.
	Flows *OAuthFlows `yaml:"flows,omitempty"`

	// OpenIDConnectURL is REQUIRED. OpenId Connect URL to discover OAuth2
	// configuration values. This MUST be in the form of a URL. The OpenID Connect
	// standard requires the use of TLS.
	OpenIDConnectURL string `yaml:"openIdConnectUrl,omitempty"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

SecurityScheme defines a security scheme that can be used by the operations.

Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2’s common flows (implicit, password, client credentials and authorization code) as defined in [RFC6749], and OpenID Connect Discovery. Please note that as of 2020, the implicit flow is about to be deprecated by OAuth 2.0 Security Best Current Practice. Recommended for most use case is Authorization Code Grant flow with PKCE.

type: http
scheme: bearer
bearerFormat: JWT

type Server

type Server struct {
	// URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.
	URL string `yaml:"url"`

	// Description of the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
	Description string `yaml:"description,omitempty"`

	// Variables map between a variable name and its value. The value is used for substitution in the server’s URL template.
	Variables map[string]*ServerVariable `yaml:"variables,omitempty"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

Server URL, optionally with variables.

servers:
- url: https://development.gigantic-server.com/v1
  description: Development server
- url: https://staging.gigantic-server.com/v1
  description: Staging server
- url: https://api.gigantic-server.com/v1
  description: Production server

type ServerVariable

type ServerVariable struct {
	// Enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT be empty.
	Enum []string `yaml:"enum,omitempty"`

	// Default value to use for substitution, which SHALL be sent if an alternate value is not supplied.
	Default string `yaml:"default"`

	// Description for the server variable. CommonMark syntax MAY be used for rich text representation.
	Description string `yaml:"description,omitempty"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

ServerVariable for server URL template substitution.

type StatusError

type StatusError interface {
	GetStatus() int
	Error() string
}

StatusError is an error that has an HTTP status code. When returned from an operation handler, this sets the response status code before sending it to the client.

func Error400BadRequest

func Error400BadRequest(msg string, errs ...error) StatusError

Error400BadRequest returns a 400.

func Error401Unauthorized

func Error401Unauthorized(msg string, errs ...error) StatusError

Error401Unauthorized returns a 401.

func Error403Forbidden

func Error403Forbidden(msg string, errs ...error) StatusError

Error403Forbidden returns a 403.

func Error404NotFound

func Error404NotFound(msg string, errs ...error) StatusError

Error404NotFound returns a 404.

func Error405MethodNotAllowed

func Error405MethodNotAllowed(msg string, errs ...error) StatusError

Error405MethodNotAllowed returns a 405.

func Error406NotAcceptable

func Error406NotAcceptable(msg string, errs ...error) StatusError

Error406NotAcceptable returns a 406.

func Error409Conflict

func Error409Conflict(msg string, errs ...error) StatusError

Error409Conflict returns a 409.

func Error410Gone

func Error410Gone(msg string, errs ...error) StatusError

Error410Gone returns a 410.

func Error412PreconditionFailed

func Error412PreconditionFailed(msg string, errs ...error) StatusError

Error412PreconditionFailed returns a 412.

func Error415UnsupportedMediaType

func Error415UnsupportedMediaType(msg string, errs ...error) StatusError

Error415UnsupportedMediaType returns a 415.

func Error422UnprocessableEntity

func Error422UnprocessableEntity(msg string, errs ...error) StatusError

Error422UnprocessableEntity returns a 422.

func Error429TooManyRequests

func Error429TooManyRequests(msg string, errs ...error) StatusError

Error429TooManyRequests returns a 429.

func Error500InternalServerError

func Error500InternalServerError(msg string, errs ...error) StatusError

Error500InternalServerError returns a 500.

func Error501NotImplemented

func Error501NotImplemented(msg string, errs ...error) StatusError

Error501NotImplemented returns a 501.

func Error502BadGateway

func Error502BadGateway(msg string, errs ...error) StatusError

Error502BadGateway returns a 502.

func Error503ServiceUnavailable

func Error503ServiceUnavailable(msg string, errs ...error) StatusError

Error503ServiceUnavailable returns a 503.

func Error504GatewayTimeout

func Error504GatewayTimeout(msg string, errs ...error) StatusError

Error504GatewayTimeout returns a 504.

func Status304NotModified

func Status304NotModified() StatusError

Status304NotModified returns a 304. This is not really an error, but provides a way to send non-default responses.

type StreamResponse

type StreamResponse struct {
	Body func(ctx Context)
}

StreamResponse is a response that streams data to the client. The body function will be called once the response headers have been written and the body writer is ready to be written to.

func handler(ctx context.Context, input *struct{}) (*huma.StreamResponse, error) {
	return &huma.StreamResponse{
		Body: func(ctx huma.Context) {
			ctx.SetHeader("Content-Type", "text/my-type")

			// Write some data to the stream.
			writer := ctx.BodyWriter()
			writer.Write([]byte("Hello "))

			// Flush the stream to the client.
			if f, ok := writer.(http.Flusher); ok {
				f.Flush()
			}

			// Write some more...
			writer.Write([]byte("world!"))
		}
	}
}

type Tag

type Tag struct {
	// Name is REQUIRED. The name of the tag.
	Name string `yaml:"name"`

	// Description for the tag. CommonMark syntax MAY be used for rich text
	// representation.
	Description string `yaml:"description,omitempty"`

	// ExternalDocs is additional external documentation for this tag.
	ExternalDocs *ExternalDocs `yaml:"externalDocs,omitempty"`

	// Extensions (user-defined properties), if any. Values in this map will
	// be marshalled as siblings of the other properties above.
	Extensions map[string]any `yaml:",inline"`
}

Tag adds metadata to a single tag that is used by the Operation Object. It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.

type Transformer

type Transformer func(ctx Context, status string, v any) (any, error)

Transformer is a function that can modify a response body before it is serialized. The `status` is the HTTP status code for the response and `v` is the value to be serialized. The return value is the new value to be serialized or an error.

type ValidateMode

type ValidateMode int

ValidateMode describes the direction of validation (server -> client or client -> server). It impacts things like how read-only or write-only fields are handled.

const (
	// ModeReadFromServer is a read mode (response output) that may ignore or
	// reject write-only fields that are non-zero, as these write-only fields
	// are meant to be sent by the client.
	ModeReadFromServer ValidateMode = iota

	// ModeWriteToServer is a write mode (request input) that may ignore or
	// reject read-only fields that are non-zero, as these are owned by the
	// server and the client should not try to modify them.
	ModeWriteToServer
)

type ValidateResult

type ValidateResult struct {
	Errors []error
}

ValidateResult tracks validation errors. It is safe to use for multiple validations as long as `Reset()` is called between uses.

func (*ValidateResult) Add

func (r *ValidateResult) Add(path *PathBuffer, v any, msg string)

Add an error to the validation result at the given path and with the given value.

func (*ValidateResult) Addf

func (r *ValidateResult) Addf(path *PathBuffer, v any, format string, args ...any)

Addf adds an error to the validation result at the given path and with the given value, allowing for fmt.Printf-style formatting.

func (*ValidateResult) Reset

func (r *ValidateResult) Reset()

Reset the validation error so it can be used again.