Huma

https://huma.rocks
Admin
Huma is a modern, simple, fast & flexible micro framework for building HTTP REST/RPC APIs in Golang...
Tokens:54,949
Snippets:668
Trust Score:7.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Restish on Windows

Source: https://huma.rocks/tutorial/cli-client

Installation command for Windows using Go.

```bash
# Go
$ go install github.com/rest-sh/restish/v2/cmd/restish@latest
```

--------------------------------

### Define a Huma API with Go

Source: https://huma.rocks/tutorial/your-first-api

A complete example showing router setup, operation registration, and input/output models.

```go
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"

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

// 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 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",
		Method:      http.MethodGet,
		Path:        "/greeting/{name}",
		Summary:     "Get a greeting",
		Description: "Get a greeting for a person by name.",
		Tags:        []string{"Greetings"},
	}, func(ctx context.Context, input *struct{
		Name string `path:"name" maxLength:"30" example:"world" doc:"Name to greet"`
	}) (*GreetingOutput, error) {
		resp := &GreetingOutput{}
		resp.Body.Message = fmt.Sprintf("Hello, %s!", input.Name)
		return resp, nil
	})

	// Start the server!
	http.ListenAndServe("127.0.0.1:8888", router)
}
```

--------------------------------

### Start the Huma server

Source: https://huma.rocks/tutorial/your-first-api

Run the Go application to start the API server.

```bash
$ go run .
```

--------------------------------

### Initialize Project Setup

Source: https://huma.rocks/tutorial/installation?q=

Placeholder command block for project initialization.

```bash
# Set up                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         
```

--------------------------------

### Install Restish on Linux

Source: https://huma.rocks/tutorial/cli-client

Installation commands for Linux using Go or Homebrew.

```bash
# Go
$ go install github.com/rest-sh/restish/v2/cmd/restish@latest

# Homebrew for Linux
$ brew install restish
```

--------------------------------

### Initialize Router and API

Source: https://huma.rocks/tutorial/your-first-api?q=

Setup for the Chi router and Huma API instance.

```go
package main

import (
	"net/http"

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

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

// 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 new router & API
	router := chi.NewMux()
	api := humachi.New(router, huma.DefaultConfig("My API", "1.0.0"))

	// TODO: Register operations...

	// Start the server!
	http.ListenAndServe("127.0.0.1:8888", router)
}
```

--------------------------------

### Install Dependencies

Source: https://huma.rocks/tutorial/your-first-api

Command to download and tidy Go module dependencies.

```bash
$ go mod tidy
```

--------------------------------

### CLI Argument Passing Examples

Source: https://huma.rocks/features/cli

Examples of passing options via command-line flags and environment variables.

```bash
# Example passing command-line args
$ go run main.go --port=8000

# Short arguments are also supported
$ go run main.go -p 8000

# Example passing by environment variables
$ SERVICE_PORT=8000 go run main.go
```

--------------------------------

### CLI Execution Examples

Source: https://huma.rocks/features/cli

Demonstrates running the CLI with default values, explicit flags, and environment variables.

```bash
// Run with defaults
$ go run main.go
I was run with debug:false host: port:8888

// Run with options
$ go run main.go --debug=true --host=localhost --port=8000
I was run with debug:true host:localhost port:8000
```

--------------------------------

### Install Restish on macOS

Source: https://huma.rocks/tutorial/cli-client

Installation commands for macOS using Homebrew or Go.

```bash
# Homebrew
$ brew install restish

# Go
$ go install github.com/rest-sh/restish/v2/cmd/restish@latest
```

--------------------------------

### Configure Alternative Router

Source: https://huma.rocks/tutorial/your-first-api?q=

Example of using the built-in Go 1.22+ ServeMux instead of Chi.

```go
router := http.NewServeMux()
api := humago.New(router, huma.DefaultConfig("My API", "1.0.0"))
```

--------------------------------

### Configure Service Port with Huma CLI

Source: https://huma.rocks/tutorial/service-configuration

Defines a CLI option for the service port using a struct with a default value. This setup allows the service to be started on a specified port, defaulting to 8888 if not provided.

```go
package main

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

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

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

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

// 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 := humacli.New(func(hooks humacli.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",
			Method:      http.MethodGet,
			Path:        "/greeting/{name}",
			Summary:     "Get a greeting",
			Description: "Get a greeting for a person by name.",
			Tags:        []string{"Greetings"},
		}, func(ctx context.Context, input *struct{
			Name string `path:"name" maxLength:"30" example:"world" doc:"Name to greet"`
		}) (*GreetingOutput, error) {
			resp := &GreetingOutput{}
			resp.Body.Message = fmt.Sprintf("Hello, %s!", input.Name)
			return resp, nil
		})

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

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

```

--------------------------------

### Full Example: Custom Validation and Exhaustive Errors

Source: https://huma.rocks/how-to/custom-validation

This example demonstrates using custom resolvers (`IntNot3`) with `minimum`, `maximum`, and `multipleOf` validators for path, query, header, and body parameters. It shows how Huma returns exhaustive errors for multiple validation failures.

```go
// This example shows how to use resolvers to provide additional validation
// for params and body fields, and how exhaustive errors are returned.
//
//	# Example call returning seven errors
//	restish put :8888/count/3?count=15 -H Count:-3 count:9, nested.subCount: 6
//
//	# Example success
//	restish put :8888/count/1 count:2, nested.subCount: 4
package main

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

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

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

// Create a new input type with additional validation attached to it.
type IntNot3 int

// Resolve is called by Huma to validate the input. Prefix is the current
// path like `path.to[3].field`, e.g. `query.count` or `body.nested.subCount`.
// Resolvers can also be attached to structs to provide validation across
// multiple field combinations, e.g. "if foo is set then bar must be a
// multiple of foo's value". Use `prefix.With("bar")` in that scenario.
func (i IntNot3) Resolve(ctx huma.Context, prefix *huma.PathBuffer) []error {
	if i != 0 && i%3 == 0 {
		return []error{&huma.ErrorDetail{
			Location: prefix.String(),
			Message:  "Value cannot be a multiple of three",
			Value:    i,
		}}
	}
	return nil
}

// Ensure our resolver meets the expected interface.
var _ huma.ResolverWithPath = (*IntNot3)(nil)

func main() {
	// Create the CLI, passing a function to be called with your custom options
	// after they have been parsed.
	cli := humacli.New(func(hooks humacli.Hooks, options *Options) {
		router := chi.NewMux()

		api := humachi.New(router, huma.DefaultConfig("My API", "1.0.0"))

		// Register the greeting operation.
		huma.Register(api, huma.Operation{
			OperationID: "put-count",
			Summary:     "Put a count of things",
			Method:      http.MethodPut,
			Path:        "/count/{count}",
		}, func(ctx context.Context, input *struct {
			PathCount   IntNot3 `path:"count" example:"2" minimum:"1" maximum:"10"
			QueryCount  IntNot3 `query:"count" example:"2" minimum:"1" maximum:"10"
			HeaderCount IntNot3 `header:"Count" example:"2" minimum:"1" maximum:"10"
			Body        struct {
				Count  IntNot3 `json:"count" example:"2" minimum:"1" maximum:"10"
				Nested *struct {
					SubCount IntNot3 `json:"subCount" example:"2" minimum:"1" maximum:"10"
				} `json:"nested,omitempty"
			}
		}) (*struct{}, error) {
			fmt.Printf("Got input: %+v\n", input)
			return nil, nil
		})

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

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

```

--------------------------------

### View CLI Help and Version Output

Source: https://huma.rocks/features/cli

Example terminal output showing the effect of setting the app name and version on help and version commands.

```bash
$ go run ./demo --help
Usage:
  appname [flags]

Flags:
  -h, --help            help for appname
  -p, --port int         (default 8888)
  -v, --version         version for appname

$ go run ./demo --version
appname version 1.0.1
```

--------------------------------

### Advanced Validation Example with Resolvers and Multiple Fields

Source: https://huma.rocks/how-to/custom-validation?q=

This example demonstrates using custom resolvers for complex validation across multiple input fields (path, query, header, body) and shows how exhaustive errors are returned. The IntNot3 type ensures values are not multiples of three.

```go
// This example shows how to use resolvers to provide additional validation
// for params and body fields, and how exhaustive errors are returned.
//
//	# Example call returning seven errors
//	restish put :8888/count/3?count=15 -H Count:-3 count:9, nested.subCount: 6
//
//	# Example success
//	restish put :8888/count/1 count:2, nested.subCount: 4
package main

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

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

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

// Create a new input type with additional validation attached to it.
type IntNot3 int

// Resolve is called by Huma to validate the input. Prefix is the current
// path like `path.to[3].field`, e.g. `query.count` or `body.nested.subCount`.
// Resolvers can also be attached to structs to provide validation across
// multiple field combinations, e.g. "if foo is set then bar must be a
// multiple of foo's value". Use `prefix.With("bar")` in that scenario.
func (i IntNot3) Resolve(ctx huma.Context, prefix *huma.PathBuffer) []error {
	if i != 0 && i%3 == 0 {
		return []error{&huma.ErrorDetail{
			Location: prefix.String(),
			Message:  "Value cannot be a multiple of three",
			Value:    i,
		}}
	}
	return nil
}

// Ensure our resolver meets the expected interface.
var _ huma.ResolverWithPath = (*IntNot3)(nil)

func main() {
	// Create the CLI, passing a function to be called with your custom options
	// after they have been parsed.
	cli := humacli.New(func(hooks humacli.Hooks, options *Options) {
		router := chi.NewMux()

		api := humachi.New(router, huma.DefaultConfig("My API", "1.0.0"))

		// Register the greeting operation.
		huma.Register(api, huma.Operation{
			OperationID: "put-count",
			Summary:     "Put a count of things",
			Method:      http.MethodPut,
			Path:        "/count/{count}",
		}, func(ctx context.Context, input *struct {
			PathCount   IntNot3 `path:"count" example:"2" minimum:"1" maximum:"10"`
			QueryCount  IntNot3 `query:"count" example:"2" minimum:"1" maximum:"10"`
			HeaderCount IntNot3 `header:"Count" example:"2" minimum:"1" maximum:"10"`
			Body        struct {
				Count  IntNot3 `json:"count" example:"2" minimum:"1" maximum:"10"`
				Nested *struct {
					SubCount IntNot3 `json:"subCount" example:"2" minimum:"1" maximum:"10"`
				} `json:"nested,omitempty"`
			}
		}) (*struct{}, error) {
			fmt.Printf("Got input: %+v\n", input)
			return nil, nil
		})

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

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

```

--------------------------------

### Configure Router-specific Middleware

Source: https://huma.rocks/features/middleware?q=

Examples of applying middleware directly to Chi and Fiber routers before initializing the Huma API.

```go
router := chi.NewMux()
router.Use(jwtauth.Verifier(tokenAuth))
api := humachi.New(router, huma.DefaultConfig("My API", "1.0.0"))
```

```go
app := fiber.New()
app.Use(logger.New())
api := humafiber.New(app, huma.DefaultConfig("My API", "1.0.0"))
```

--------------------------------

### Call API Operations via CLI

Source: https://huma.rocks/features/bring-your-own-router

Example commands to interact with the demo operation and retrieve the OpenAPI specification.

```shell
# Call the demo operation
restish :8888/api/demo

# Get the OpenAPI
restish :8888/api/openapi.yaml
```

--------------------------------

### Restish CLI Command Example

Source: https://huma.rocks/features/operations

This example demonstrates how the OperationID is used to generate friendly CLI commands with the Restish tool.

```bash
$ restish your-api your-operation-name --param=value ...
```

--------------------------------

### Define Custom Options Struct

Source: https://huma.rocks/features/cli

Example of defining an options struct with struct tags for documentation, naming, and defaults.

```go
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"`
}
```

--------------------------------

### Make a request to the API

Source: https://huma.rocks/tutorial/your-first-api

Use curl to send a GET request to the greeting endpoint.

```bash
# Get a greeting from the API
$ curl http://localhost:8888/greeting/world
```

--------------------------------

### Using Huma Convenience Methods (GET)

Source: https://huma.rocks/features/operations?q=

Convenience methods like `huma.Get` simplify operation registration by inferring the HTTP method and generating an `OperationID` based on the path. Use `huma.Register` directly if more control is needed.

```go
huma.Get(api, "/things/{thing-id}", func(ctx context.Context, input *YourInput) (*YourOutput, error) {
    // ... Implementation goes here ...
})

```

--------------------------------

### Execute Requests via CLI

Source: https://huma.rocks/features/request-inputs

Examples of invoking an API endpoint using high-level operations or direct URL paths.

```bash
# 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
```

--------------------------------

### Example HTTP Response Link Header

Source: https://huma.rocks/features/json-schema-registry

This header provides a link to the JSON Schema describing the resource. It's automatically generated by Huma.

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

--------------------------------

### Example OpenAPI JSON with Custom Extension

Source: https://huma.rocks/features/openapi-generation

Illustrates the resulting OpenAPI JSON output when a custom extension is added to the configuration. The custom extension appears as a peer to standard fields like 'openapi' and 'info'.

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

--------------------------------

### Implement a Custom JSON Format

Source: https://huma.rocks/features/response-serialization

Define a custom format by implementing the 'huma.Format' interface. This example shows a simple JSON format using Go's standard 'encoding/json' package.

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

--------------------------------

### Make Requests to Test API

Source: https://huma.rocks/features/test-utilities?q=

Utilize convenience methods like Get and Put on the test API object to simulate HTTP requests. Arguments can include headers, raw bodies, or JSON payloads.

```go
func TestMyAPI(t *testing.T) {
	router, api := humatest.New(t)

	// Register routes...
	addRoutes(api)

	// Make a GET request
	resp := api.Get("/some/path?foo=bar")

	// Make a PUT request
	resp = api.Put("/some/path",
		"My-Header: abc123",
		map[string]any{
			"author": "daniel",
			"rating": 5,
		})
}
```

--------------------------------

### Add OpenAPI Client Auto-Configuration Extension

Source: https://huma.rocks/how-to/oauth2-jwt?q=

Applies the `x-cli-config` extension to the OpenAPI specification to enable client auto-configuration, facilitating automatic setup of authentication mechanisms.

```go
config.Extensions["x-cli-config"] = huma.AutoConfig{ /* ... */ }
```

--------------------------------

### GET /things/{thing-id}

Source: https://huma.rocks/features/response-errors

Example of returning a 404 Not Found error from a handler function.

```APIDOC
## GET /things/{thing-id}

### Description
Retrieves a specific thing by its ID. Returns a 404 error if the resource is not found.

### Method
GET

### Endpoint
/things/{thing-id}

### Parameters
#### Path Parameters
- **thing-id** (string) - Required - The unique identifier of the thing.

### Response
#### Error Response (404)
- **status** (integer) - HTTP status code
- **title** (string) - Error title
- **detail** (string) - Error description
```

--------------------------------

### Initialize and use the Go SDK client

Source: https://huma.rocks/tutorial/client-sdks

Demonstrates initializing the SDK client with a base URL and performing a greeting request. Ensure the context is properly managed and error handling is implemented for non-200 status codes.

```go
package main

import (
	"context"
	"fmt"

	"github.com/my-user/my-api/sdk"
)

func main() {
	ctx := context.Background()

	// Initialize an SDK client.
	client, _ := sdk.NewClientWithResponses("http://localhost:8888")

	// Make the greeting request.
	greeting, err := client.GetGreetingWithResponse(ctx, "world")
	if err != nil {
		panic(err)
	}

	if greeting.StatusCode() > 200 {
		panic(greeting.ApplicationproblemJSONDefault)
	}

	// Everything was successful, so print the message.
	fmt.Println(greeting.JSON200.Message)
}
```

--------------------------------

### Manage Server Lifecycle with Hooks

Source: https://huma.rocks/features/cli

Use OnStart and OnStop hooks to manage HTTP server startup and graceful shutdown.

```go
cli := humacli.New(func(hooks humacli.Hooks, opts *Options) {
	// Set up the router and API
	// ...

	// Create the HTTP server.
	server := http.Server{
		Addr:    fmt.Sprintf(":%d", options.Port),
		Handler: router,
	}

	hooks.OnStart(func() {
		// Start your server here
		server.ListenAndServe()
	})

	hooks.OnStop(func() {
		// Gracefully shutdown your server here
		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
		defer cancel()
		server.Shutdown(ctx)
	})
})
```

--------------------------------

### Define and Run a Basic CLI

Source: https://huma.rocks/features/cli

Define service options using a struct and initialize the CLI with a handler function.

```go
// 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 := humacli.New(func(hooks humacli.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()
}
```

--------------------------------

### Shorthand Merge Patch Example

Source: https://huma.rocks/features/auto-patch?q=

An example of a shorthand merge patch syntax used to append an item to an array.

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

--------------------------------

### Initialize Project Dependency

Source: https://huma.rocks/tutorial/installation

Command to prepare the project for Huma imports.

```bash
# Set
```

--------------------------------

### Initialize Router and API

Source: https://huma.rocks/tutorial/your-first-api

Sets up a Chi router and Huma API instance, with an alternative provided for the standard Go 1.22+ ServeMux.

```go
package main

import (
	"net/http"

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

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

// 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 new router & API
	router := chi.NewMux()
	api := humachi.New(router, huma.DefaultConfig("My API", "1.0.0"))

	// TODO: Register operations...

	// Start the server!
	http.ListenAndServe("127.0.0.1:8888", router)
}
```

```go
router := http.NewServeMux()
api := humago.New(router, huma.DefaultConfig("My API", "1.0.0"))
```

--------------------------------

### Test GET /greeting/{name}

Source: https://huma.rocks/tutorial/writing-tests

Tests the GET /greeting/{name} endpoint using humatest. It checks if the response body contains the expected greeting message.

```go
package main

import (
	"strings"
	"testing"

	"github.com/danielgtaylor/huma/v2/humatest"
)

func TestGetGreeting(t *testing.T) {
	_, api := humatest.New(t)

	addRoutes(api)

	resp := api.Get("/greeting/world")
	if !strings.Contains(resp.Body.String(), "Hello, world!") {
		t.Fatalf("Unexpected response: %s", resp.Body.String())
	}
}

```

--------------------------------

### Shorthand Merge Patch Example

Source: https://huma.rocks/features/auto-patch

This example demonstrates a Shorthand Merge Patch format for appending an item to an array, creating it if it doesn't exist. This format extends JSON merge patch with support for field paths and arrays.

```json
{
	"foo.bar[]": "baz"
}
```

--------------------------------

### GET /greeting/{name}

Source: https://huma.rocks/tutorial/service-configuration?q=

Retrieves a personalized greeting message.

```APIDOC
## GET /greeting/{name}

### Description
Get a greeting for a person by name.

### Method
GET

### Endpoint
/greeting/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - Name to greet

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **message** (string) - Greeting message

#### Response Example
```json
{
  "message": "Hello, world!"
}
```
```

--------------------------------

### Define Options with a Struct and Use humacli.New

Source: https://huma.rocks/how-to/migrate?q=

Define service options using a struct and wrap the service with `humacli.New`.

```go
humacli.New
```

--------------------------------

### GET /sse

Source: https://huma.rocks/features/server-sent-events-sse?q=

Registers an SSE endpoint to stream events to the client.

```APIDOC
## GET /sse

### Description
Registers a streaming endpoint that pushes events to the client. The handler receives a `sse.Sender` to transmit data.

### Method
GET

### Endpoint
/sse

### Request Body
- **mapping** (map[string]any) - Required - A map of event type names to Go structs for OpenAPI documentation.

### Request Example
```go
sse.Register(api, huma.Operation{
	OperationID: "sse",
	Method:      http.MethodGet,
	Path:        "/sse",
	Summary:     "Server sent events example",
}, map[string]any{
	"message":      DefaultMessage{},
	"userCreate":   UserCreatedEvent{},
	"mailReceived": MailReceivedEvent{},
}, func(ctx context.Context, input *struct{}, send sse.Sender) {
	// Handler logic
})
```
```

--------------------------------

### Project Directory Structure

Source: https://huma.rocks/tutorial/installation

The expected file layout after initializing a new Go project.

```text
my-api/
  |-- go.mod
  |-- go.sum
```

--------------------------------

### GET /set-cookie

Source: https://huma.rocks/features/response-outputs?q=

Demonstrates how to set cookies in the response using the Set-Cookie header.

```APIDOC
## GET /set-cookie

### Description
Sets a session cookie in the response header.

### Method
GET

### Endpoint
/set-cookie

### Response
#### Success Response (200)
- **Set-Cookie** (http.Cookie) - The cookie to be set in the response.
```

--------------------------------

### Initialize and Run Huma CLI

Source: https://huma.rocks/features/cli?q=

Initialize the Huma CLI with a callback function that receives hooks and options. The CLI can then be run using `cli.Run()`.

```go
func main() {
	// Then, create the CLI.
	cli := humacli.New(func(hooks humacli.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()
}
```

--------------------------------

### Initialize Huma with Chi Router

Source: https://huma.rocks/features/bring-your-own-router?q=

Instantiate a Huma API by wrapping a Chi router and providing a configuration object. Ensure the correct adapter (`humachi`) is imported.

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

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

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

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

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

```

--------------------------------

### Service Configuration Options

Source: https://huma.rocks/tutorial/service-configuration?q=

Demonstrates how to define and use CLI options for service configuration, including port settings.

```APIDOC
## Service Configuration

Huma provides a command-line and environment variable parser for runtime configuration.

### Port Option

Define a struct for CLI options, including a port with a default value.

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

### Passing Options

Options can be passed via command-line arguments or environment variables prefixed with `SERVICE_`.

**Command-line Arguments:**
```bash
$ go run main.go --port=8000
$ go run main.go -p 8000
```

**Environment Variables:**
```bash
$ SERVICE_PORT=8000 go run main.go
```

### Precedence

Command-line arguments take priority over environment variables if both are present.
```

--------------------------------

### GET /things/{thing-id}

Source: https://huma.rocks/features/response-outputs?q=

Retrieves a thing by ID with a dynamic status code based on the input.

```APIDOC
## GET /things/{thing-id}

### Description
Retrieves a specific thing by its ID. The response status code is determined dynamically based on the input ID.

### Method
GET

### Endpoint
/things/{thing-id}

### Parameters
#### Path Parameters
- **thing-id** (string) - Required - The unique identifier of the thing.

### Response
#### Success Response (200/250)
- **Status** (int) - The dynamically assigned status code.
```

--------------------------------

### Initialize Huma with Chi Router (v4)

Source: https://huma.rocks/features/bring-your-own-router?q=

For existing services using Chi v4, use the `humachi.NewV4` function instead of `humachi.New`.

```go
api := humachi.NewV4(router, huma.DefaultConfig("My API", "1.0.0"))
```

--------------------------------

### GET /things/{thing-id}

Source: https://huma.rocks/features/response-outputs

Retrieves a thing by ID with a dynamic status code based on the input.

```APIDOC
## GET /things/{thing-id}

### Description
Retrieves a specific thing by its ID. The response status code is determined dynamically based on the input ID.

### Method
GET

### Endpoint
/things/{thing-id}

### Parameters
#### Path Parameters
- **thing-id** (string) - Required - The unique identifier of the thing.

### Response
#### Success Response (200/250)
- **Status** (int) - The dynamic status code returned by the operation.
```

--------------------------------

### Initialize Huma with Chi Router

Source: https://huma.rocks/features/bring-your-own-router

Wraps a Chi router instance with Huma to create an API. Requires the humachi adapter package.

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

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

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

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

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

--------------------------------

### Initialize Restish

Source: https://huma.rocks/tutorial/cli-client?q=

Run the restish command to begin configuration.

```bash
$ restish
```

--------------------------------

### Register API Operation

Source: https://huma.rocks/tutorial/your-first-api

Registers a GET handler that extracts a path parameter and returns a greeting message.

```go
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"

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

// 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 new router & API.
	router := chi.NewMux()
	api := humachi.New(router, huma.DefaultConfig("My API", "1.0.0"))

	// Register GET /greeting/{name} handler.
	huma.Get(api, "/greeting/{name}", func(ctx context.Context, input *struct{
		Name string `path:"name" maxLength:"30" example:"world" doc:"Name to greet"`
	}) (*GreetingOutput, error) {
		resp := &GreetingOutput{}
		resp.Body.Message = fmt.Sprintf("Hello, %s!", input.Name)
		return resp, nil
	})

	// Start the server!
	http.ListenAndServe("127.0.0.1:8888", router)
}
```

--------------------------------

### Using Convenience Methods for Operations

Source: https://huma.rocks/features/operations

Convenience methods like huma.Get simplify operation registration by inferring the HTTP method and generating an operation ID based on the path. Use huma.Register directly for more control.

```go
huma.Get(api, "/things/{thing-id}", func(ctx context.Context, input *YourInput) (*YourOutput, error) {
    // ... Implementation goes here ...
})
```

--------------------------------

### POST /text

Source: https://huma.rocks/features/request-inputs?q=

Example of an operation that bypasses normal body parsing to read raw body contents directly as bytes.

```APIDOC
## POST /text

### Description
Example to post plain text input by reading the raw body contents directly.

### Method
POST

### Endpoint
/text

### Request Body
- **RawBody** ([]byte) - Required - The raw body content of the request.
```

--------------------------------

### Running Tests via Terminal

Source: https://huma.rocks/tutorial/writing-tests?q=

Execute the standard Go test command to run the suite.

```bash
$ go test -cover
```

--------------------------------

### API Request and Response Design

Source: https://huma.rocks/tutorial/sending-data

Example structure for a POST request to submit a review and the expected 201 Created response.

```json
Request:
POST /reviews
{
	"author": "Daniel",
	"rating": 5,
	"message": "Some custom review message"
}

Response: 201 Created
```

--------------------------------

### Create a Test API Instance

Source: https://huma.rocks/features/test-utilities?q=

Initialize a new test API instance using humatest.New. This instance can be registered with routes and used for making requests.

```go
import (
	t"testing"

	"github.com/danielgtaylor/huma/v2/humatest"
)

func TestMyAPI(t *testing.T) {
	router, api := humatest.New(t)
}
```

--------------------------------

### Test GET /greeting/{name} with Context

Source: https://huma.rocks/tutorial/writing-tests

Demonstrates how to test an endpoint with a custom context.Context. The `GetCtx` method is used to pass the context to the request.

```go
package main

import (
	"context"
	"strings"
	"testing"

	"github.com/danielgtaylor/huma/v2/humatest"
)

func TestGetGreeting(t *testing.T) {
	_, api := humatest.New(t)

	addRoutes(api)
	
	ctx := context.Background() // define your necessary context

	resp := api.GetCtx(ctx, "/greeting/world") // provide it using the 'Ctx' suffixed methods
	if !strings.Contains(resp.Body.String(), "Hello, world!") {
		t.Fatalf("Unexpected response: %s", resp.Body.String())
	}
}

```

--------------------------------

### Run Service with Custom Port via CLI

Source: https://huma.rocks/tutorial/service-configuration

Demonstrates how to run the Huma service with a specified port using command-line arguments. Short arguments are also supported.

```bash
$ go run main.go --port=8000
```

```bash
$ go run main.go -p 8000
```

--------------------------------

### Register Routes for Testing

Source: https://huma.rocks/tutorial/writing-tests

Move operation registration out of main to facilitate testing. This function registers GET and POST endpoints for greetings and reviews.

```go
package main

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

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

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

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

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

// ReviewInput represents the review operation request.
type ReviewInput struct {
	Body struct {
		Author  string `json:"author" maxLength:"10" doc:"Author of the review"`
		Rating  int    `json:"rating" minimum:"1" maximum:"5" doc:"Rating from 1 to 5"`
		Message string `json:"message,omitempty" maxLength:"100" doc:"Review message"`
	}
}

func addRoutes(api huma.API) {
	// Register GET /greeting/{name}
	huma.Register(api, huma.Operation{
		OperationID: "get-greeting",
		Method:      http.MethodGet,
		Path:        "/greeting/{name}",
		Summary:     "Get a greeting",
		Description: "Get a greeting for a person by name.",
		Tags:        []string{"Greetings"},
	}, func(ctx context.Context, input *struct{
		Name string `path:"name" maxLength:"30" example:"world" doc:"Name to greet"`
	}) (*GreetingOutput, error) {
		resp := &GreetingOutput{}
		resp.Body.Message = fmt.Sprintf("Hello, %s!", input.Name)
		return resp, nil
	})

	// Register POST /reviews
	huma.Register(api, huma.Operation{
		OperationID:   "post-review",
		Method:        http.MethodPost,
		Path:          "/reviews",
		Summary:       "Post a review",
		Tags:          []string{"Reviews"},
		DefaultStatus: http.StatusCreated,
	}, func(ctx context.Context, i *ReviewInput) (*struct{}, error) {
		// TODO: save review in data store.
		return nil, nil
	})
}

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

		addRoutes(api)

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

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

```

--------------------------------

### Huma Micro Benchmarks

Source: https://huma.rocks/why/benchmarks

Comparison of benchmark results for Huma v1, Huma v2, and raw Chi router performance.

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

# Huma v2
BenchmarkHumaV2Chi-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
```

--------------------------------

### Use humachi.NewV4 Adapter

Source: https://huma.rocks/how-to/migrate?q=

Huma V2 uses the humachi.NewV4 adapter, as Huma V1 relies on Chi v4.

```go
humachi.NewV4
```

--------------------------------

### Call Demo Operation and Get OpenAPI Spec

Source: https://huma.rocks/features/bring-your-own-router?q=

Use `restish` to call a demo operation on the `/api/demo` endpoint or retrieve the OpenAPI specification from `/api/openapi.yaml`.

```shell
# Call the demo operation
restish :8888/api/demo

# Get the OpenAPI
restish :8888/api/openapi.yaml

```
Tokens:
Raw