Huma

Huma is an OpenAPI REST framework for Go designed for building HTTP services with automatic OpenAPI 3.1 specification generation and JSON Schema validation. It serves as a toolkit for developing REST and RPC APIs with typed inputs and outputs, deriving interactive documentation directly from the source code.

The framework distinguishes itself by automating the synchronization between implementation and documentation. It uses a content-negotiation engine to manage multiple serialization formats via client headers and employs a JSON Schema input validator to automatically verify request parameters and bodies based on Go types.

The project covers a broad range of API capabilities, including request parameter binding via struct tags, the management of conditional requests using ETags, and the implementation of partial updates. It also provides tools for server lifecycle management, including command-line configuration, graceful shutdowns, and the integration of custom HTTP routers via a standardized adapter interface.

Features

Type-Derived JSON Schemas - Automatically generates JSON Schema validation rules from Go types to verify incoming request data.

RESTful API Development - Building HTTP services with typed inputs and outputs while automating the generation of OpenAPI specifications.

OpenAPI Specification Generators - Automatically generates OpenAPI 3.1 specifications directly from Go code structures to ensure documentation stays in sync.

API Documentation Generators - Produces up-to-date OpenAPI 3.1 specifications directly from source code to maintain accurate API documentation.

Handler Route Mapping - Provides the core mechanism for mapping URL paths to handler functions using structured input and output models.

Request Parameter Parsing - Uses Go struct tags to automatically parse and bind values from paths, query strings, headers, and cookies.

Input Validation Schemas - Automatically generates JSON Schemas from Go types to validate request data and return standard errors.

Data Validation Schemas - Checks request parameters against schemas or custom logic and returns detailed error messages.

Validation Constraints - Uses Go struct tags to define input constraints that automatically generate JSON Schemas and documentation.

Request Middleware - Implements a request middleware pipeline to handle cross-cutting concerns like authentication, metrics, and tracing.

API Parameter Validation - Enforces strict constraints such as numeric ranges and maximum lengths on API request parameters.

API Resource Mapping - Implements the mapping of HTTP methods and resource paths to handler functions with strongly typed inputs and outputs.

Content Negotiation - Manages data exchange by supporting multiple content types like JSON and CBOR via the Accept header.

Content Negotiation Pipelines - Includes a content-negotiation engine that selects serialization formats based on client Accept headers.

Middleware Frameworks - Implements a request processing chain for handling cross-cutting concerns like authentication and tracing.

Request Middleware - Provides mechanisms for injecting custom logic into the request pipeline globally or on a per-operation basis.

Content Negotiation - Determines request and response formats by matching Content-Type and Accept headers.

Response Serialization - Provides a configurable pipeline for converting Go objects into various serialization formats for transmission.

REST API Frameworks - Offers a structured framework for building HTTP endpoints with native support for request parameters, bodies, and response headers.

REST API Services - Provides a framework for building HTTP services that support both REST and RPC patterns with automated documentation.

OpenAPI Frameworks - Serves as a comprehensive toolkit for building Go HTTP services with integrated OpenAPI 3.1 generation and validation.

Command-Line Argument Parsers - Maps typed Go structures to command-line flags with support for default values and aliases.

Interactive Documentation Interfaces - Generates a web interface that renders OpenAPI specifications for real-time testing and exploration of endpoints.

Command Line Configuration Interfaces - Bootstraps servers with a command-line interface for managing runtime configuration and environment variables.

Server Lifecycles - Provides built-in tools for managing server startup and executing graceful shutdowns of HTTP services.

Service CLI Wrappers - Creates a command-line layer to handle startup arguments, environment variable binding, and graceful shutdown logic.

Service Lifecycle Management - Handles application startup and graceful shutdowns using configuration arguments or environment variables.

Authentication Documentation - Defines security requirements and token flows within the specification to inform clients how to authenticate.

Custom Schema Definitions - Applies advanced JSON Schema validation rules, including negation and schema unions, for custom API inputs.

API Route Groups - Groups API operations under common base URL paths to support versioning and organized documentation.

Partial Update Strategies - Implements architectural patterns for partial resource updates using PATCH operations.

Authorization Validation - Inspects request headers for valid tokens and verifies that users possess required scopes for an operation.

Struct Tag Binding - Maps HTTP path, query, and header values to typed Go structures using declarative struct tags.

OpenAPI Response Definitions - Maps response bodies and headers to Go structs to automate output formatting and OpenAPI response definitions.

Response Header Modifiers - Allows assigning custom headers and cookies to outgoing responses using declarative struct tags.

Request and Response Transformers - Provides mechanisms to modify structured response data and inject headers after the handler executes.

RFC 7807 Implementations - Produces machine-readable error responses following the RFC 7807 Problem Details for HTTP APIs standard.

Descriptive HTTP Error Responses - Implements standardized error responses using the RFC 9457 Problem Details format.

HTTP Routers - Provides a standardized adapter interface to decouple the framework from various HTTP routing libraries.

Partial Update Operations - Create partial update endpoints based on existing resources using merge patch formats and conditional headers.

Pluggable Serialization Formats - Adds support for new data formats by providing custom marshal and unmarshal functions.

Structured Body Binding - Maps HTTP request bodies to structured Go types using configurable content types and optionality settings.

Request Data Transformation - Executes custom transformation logic on incoming request data before it reaches the handler.

Specification Customizations - Provides configuration options to inject custom security schemes and extensions into the generated OpenAPI specification.

Route Grouping - Organizes API endpoints into logical hierarchies to share common middleware and path prefixes.

Router Adapters - Connect to any HTTP router via a standard adapter interface to add functionality to existing services.

Schema Customization - Allows overriding generated OpenAPI schemas to define custom validation rules and documentation for request and response bodies.

Strict Schema Validation - Allows rejecting requests that contain unexpected fields not defined in the JSON schema to prevent input errors.

danielgtaylorhuma

Features

Star history