Skip to content

Huma Issues

Jump to bottom
MeGaNeKo edited this page Mar 20, 2026 · 1 revision

Huma Issues Addressed

This page tracks which open Huma issues Neoma solves.

Solved

# Title How
301 Nested header on input Binding recurses into nested structs
393 Nullable query params Pointer types for query params
401 Override ErrorModel for single operations SkipDiscoveredErrors + ErrorExamples per operation
414 Validation errors localization core.MsgXxx vars overridable for i18n
429 Multiline doc description Works with backtick struct tags
430 Hidden ops still emit schemas ExcludeHiddenSchemas config, MarshalJSON filtering
444 Unexported embedded fields Processes promoted fields from unexported embedded structs
453 Accessing validation results Resolvers receive context
455 readOnly on object types Recursive readOnly/writeOnly enforcement in validation
470 Catch and log 500s ErrorHandler receives all errors with context
475 Error headers always appends ErrorWithHeaders uses SetHeader (replaces by key)
476 Unable to set write deadline SSE handles deadline gracefully
482 Custom error types from handlers ErrorHandler interface, any struct with StatusCode() + Error()
486 Use net/http.Handler directly adapters/neomastdlib
488 Custom types for list query params TextUnmarshaler support for slice elements
500 OAuth in SwaggerUI SwaggerUIProvider.OAuthClientID and OAuthScopes
541 Middleware testing middleware.TestMiddleware, TestChain, TestBuilder
560 Primitive types not reused Custom primitive types get named $ref
574 Errors in StreamResponse StreamResponse.Body receives (ctx, api), call WriteErr before streaming
588 Separate internal and external routes Dual spec with hidden:"true" on fields/params/operations
590 Middleware can't access route info Context.MatchedPattern()
600 String enum validation Consistent enum comparison with type coercion
614 Request-side transformer Transformers on Config
617 Anonymous fields as params Promoted fields from embedded structs
621 Named enum types in OAS Enum types registered as named schemas
636 array[T] naming in docs Arrays of named types reference by name
638 propertyNames support Supported via struct tags
679 Logging errors in middleware ErrorHandler receives all errors, middleware wraps handler
680 Default for non-string type panics Type checking before conversion
684 Route groups break docs Group prefixes properly prepended
691 Improve middleware for groups middleware.NewGroup with UseMiddleware, UseModifier, UseTransformer
692 Header tag on generic types Binding walks through generic type params
698 int64 as string json:",string" tag detected
716 Resolver dives into nested fields Configurable via Operation metadata
755 Get rid of exported global variables Zero global mutable state
761 oneOf, anyOf, allOf, not via struct tags Supported
787 Incorrect allOf validation Proper schema merge for embedded struct composition
789 Custom body marshaler ignored Checks for json.Marshaler interface
804 Group modifier middleware not working middleware.Group properly injects middleware
808 ErrorDetail.Value leaks data Validation checks interfaces before echoing
809 humacli logging on stderr neomacli.WithLogger
811 Access http.Request in resolver Unwrap() on each adapter
814 Default tag panic with generic wrapper Safe default parsing with type checking
823 Suppress validation per-type SkipValidateBody/SkipValidateParams on Operation
839 Enum body vs query inconsistency Unified type coercion
852 Secure docs endpoint DocsConfig.Middlewares and InternalSpec.Middlewares
853 Headers in error response in OpenAPI Operation.ErrorHeaders and Operation.ErrorResponses
859 WithValue + context.Unwrap loses values core.UnwrapContext preserves context chain
864 Multiple media types per operation contentType tag on Body field
868 format:uuid in schema UUID types emit format: "uuid"
870 Recursive struct parameters Binding recurses into nested structs
878 Can't set Errors in group modifier Settable in modifiers
880 Remove default error schema ErrorHandler.ErrorSchema() returns nil, NoopHandler built-in
885 Localizer for error by request header ErrorHandler.NewErrorWithContext receives request context
888 SSE deadline failed to flush SSE unwraps writer to find Flusher
894 Faulty duplicate detection panic Deterministic naming with collision detection
897 Multipart struct parsing panic Safe struct field iteration
920 Fiber v3 support adapters/neomafiber/v3
922 Regex in path params breaks OpenAPI Stripped from path when building spec
929 OpenAPI v3.2 tag nesting Tags []*Tag field on core.Tag
933 Middleware before route resolution api.UseGlobalMiddleware()
935 Middleware with access to input/output Operation.Metadata + middleware.Builder
956 Stop generating schemas for request args Use anonymous struct for Body to avoid component registration
957 Echo v5 support adapters/neomaecho/v5
958 ParamWrapper + MultipartFormFiles Multipart form handling with form tags, core.FormFile, ParamWrapper
991 Request body examples Auto-built from example tags and ExampleProvider

Not Ported

Autopatch was not ported due to its fragile implementation. Generating PATCH operations from GET/PUT pairs requires assumptions about the data model that frequently break in practice.

# Title
634 Autopatch: nullable fields
747 Autopatch: supported formats
748 Autopatch: operation definition
753 Autopatch: response encoding
914 Autopatch: GenerateOperationID

User Responsibility

These are achievable with the existing framework but depend on user choices and their router.

# Title How
377 API versioning Path-based: use middleware.NewGroup(api, "/v1"). Header-based: use middleware to read Accept or X-API-Version and dispatch. Content-type-based (e.g., application/vnd.myapi.v2+json): use the contentType tag on Body fields. Multiple strategies exist (URL prefix, header, content type); the framework supports all of them but doesn't prescribe one.
896 Wildcard/greedy path params Use the router's wildcard syntax (e.g., Chi: /files/{path}, Fiber: /files/*). ctx.Param() returns whatever the router captures. Note: the OAS docs UI may send the literal * instead of the path when testing.
985 Header-based routing Related to #377. Use middleware to inspect Content-Type or custom version headers and dispatch to different handlers. The OAS can document multiple content types per operation via contentType tags.

Out of Scope

# Title Why
570 WebSocket + AsyncAPI WebSocket is a different protocol. OpenAPI has no native WebSocket representation. The community discussion suggested AsyncAPI integration as a separate library on top of the framework, which the Huma creator agreed with. Users can mount any WebSocket library (gorilla/websocket, nhooyr/websocket) on their router directly. SSE covers the server push use case.
586 GraphQL support The Huma creator explicitly decided against this for v2 due to complexity. GraphQL is a fundamentally different paradigm. Users can use gqlgen or graphql-go alongside Neoma on the same router, or use tools like openapi-to-graphql to generate a GraphQL layer from the OpenAPI spec.

Clone this wiki locally