op_handler

README

Operation Handlers package

Introduction

This package provides a set of Operation Handlers that plays well with hureg library.

Operation Handlers are used in Huma to modify an operation before registration.

type OperationHandler func(op *huma.Operation)

Normally, they are passed to huma.Get(), huma.Post(), etc. functions as the last arguments.

Hureg usage

With hureg you still can use them as usual, but you can also add them to the APIGen instance to apply them to all operations registered with this instance.

derivedApi := api.AddOpHandler(oh1, oh2)

hureg.Get(derivedApi, "/cat", catHandler)  // oh1 and oh2 will be applied to the operation

Package contents

Package provides a set of Operation Handlers that can be used both in registration function (hureg.Get(), hureg.Post(), ..., hureg.Register()) and in APIGen.AddOpHandler() method to apply them to all operations registered with the APIGen instance.

Even though the handlers follow the standard Huma func(op *huma.Operation) signature, some of them require operation metadata keys specific to hureg library.

Index

What can you do with provided Operation Handlers is:

• Add Security entries to the operation
• Add Tags to the operation
• Generate operationID - can be useful for explicitly defined operations
• Generate operation Summary - can be useful for explicitly defined operations
• Conditionally apply other handlers
• Add middlewares to the operation - there is a shortcut in ApiGEN for this
• Set BodyReadTimeout field
• Set Deprecated field
• Set Description field
• Set Extension key
• Set ExternalDocs field
• Set Hidden field
• Set MaxBodyBytes field
• Set Metadata keys
• Set Responses key
• Set SkipValidateBody field
• Set Summary field
• Update generated Summary field after operation modification

Documentation

Index

• func ApplyToOperation(op huma.Operation, handlers ...OperationHandler) huma.Operation
• func ApplyToOperationPtr(op *huma.Operation, handlers ...OperationHandler)
• func SetHidden(isHidden bool, override bool) func(o *huma.Operation)
• func SetSummary(summary string, override bool) func(o *huma.Operation)
• func UpdateGeneratedSummary(op *huma.Operation)
• type OperationHandler
  • func AddBasePath(basePath string) OperationHandler
  • func AddMiddlewares(middlewares ...func(huma.Context, func(huma.Context))) OperationHandler
  • func AddSecurity(securityEntries ...map[string][]string) OperationHandler
  • func AddTags(tags ...string) OperationHandler
  • func AppendDescription(separator string, parts ...string) OperationHandler
  • func GenerateOperationID(override bool) OperationHandler
  • func GenerateSummary(override bool) OperationHandler
  • func If(condition func(op *huma.Operation) bool, handlers ...OperationHandler) OperationHandler
  • func SetBodyReadTimeout(timeout time.Duration, override bool) OperationHandler
  • func SetDeprecated(deprecated bool, override bool) OperationHandler
  • func SetDescription(description string, override bool) OperationHandler
  • func SetExtensionsKey(key string, value any, override bool) OperationHandler
  • func SetExternalDocs(externalDocs *huma.ExternalDocs, override bool) OperationHandler
  • func SetMaxBodyBytes(n int64, override bool) OperationHandler
  • func SetMetadataKey(key string, value any, override bool) OperationHandler
  • func SetResponse(statusCode int, response *huma.Response, override bool) OperationHandler
  • func SetSkipValidateBody(skipValidateBody bool, override bool) OperationHandler
  • func SetSkipValidateParams(skipValidateParams bool, override bool) OperationHandler
  • func UpdateOperationID(explicitOpIDBuilder func(*huma.Operation) string) OperationHandler

Functions

func ApplyToOperation

func ApplyToOperation(op huma.Operation, handlers ...OperationHandler) huma.Operation

ApplyToOperation is a helper method to apply multiple OperationHandlers to an Operation, returning the modified Operation.

func ApplyToOperationPtr

func ApplyToOperationPtr(op *huma.Operation, handlers ...OperationHandler)

ApplyToOperationPtr is a helper method to apply multiple OperationHandlers to an Operation pointer.

func SetHidden

func SetHidden(isHidden bool, override bool) func(o *huma.Operation)

SetHidden sets the Hidden field of the operation to the given value. If `override` is false and the operation already has Hidden set to true, it will not be changed.

func SetSummary

func SetSummary(summary string, override bool) func(o *huma.Operation)

SetSummary creates an OperationHandler that sets the Summary field on the operation. If override is `false`, it will not override the existing summary. If summary is set, it also sets the metadata key metadata.KeyIsExplicitSummary to true to inform next handlers that summary was set explicitly and should not be re-generated

func UpdateGeneratedSummary

func UpdateGeneratedSummary(op *huma.Operation)

UpdateGeneratedSummary creates an OperationHandler that re-generates the Summary field on the operation if it is not explicitly set.

Types

type OperationHandler

type OperationHandler = func(op *huma.Operation)

func AddBasePath

func AddBasePath(basePath string) OperationHandler

AddBasePath creates an OperationHandler that sets the base path (path prefix) for the operation. It updates operation`s Path and metadata.KeyBasePath.

func AddMiddlewares

func AddMiddlewares(middlewares ...func(huma.Context, func(huma.Context))) OperationHandler

AddMiddlewares creates an OperationHandler that appends the given middlewares to the operation's Middlewares field.

func AddSecurity

func AddSecurity(securityEntries ...map[string][]string) OperationHandler

AddSecurity creates an OperationHandler that appends the given security entries to the operation's AddSecurity field.

func AddTags

func AddTags(tags ...string) OperationHandler

AddTags creates an OperationHandler that appends the given tags to the operation's Tags field. If a tag is already present, it will not be duplicated.

func AppendDescription

func AppendDescription(separator string, parts ...string) OperationHandler

AppendDescription creates an OperationHandler that appends provided `parts` to the Description field of an operation separating them with `separator`.

func GenerateOperationID

func GenerateOperationID(override bool) OperationHandler

GenerateOperationID creates an OperationHandler that sets the OperationID for the operation in a way Huma does it by default. If override is `false`, it will not override existing OperationID. It's supposed to be used internally by the library, but you can use it in your registration pipeline with override == false to initialize explicitly provided operations with not specified OperationID.

func GenerateSummary

func GenerateSummary(override bool) OperationHandler

GenerateSummary creates an OperationHandler that generates a summary for the operation in a way Huma does it by default. If override is `false`, it will not override existing Summary. It's supposed to be used internally by the library, but you can use it in your registration pipeline with override == false to initialize explicitly provided operations with not specified Summary.

func If

func If(
	condition func(op *huma.Operation) bool,
	handlers ...OperationHandler,
) OperationHandler

If creates an OperationHandler that applies the given handlers if the condition is true. It's a helper method to avoid creating a separate OperationHandlers with condition checks.

func SetBodyReadTimeout

func SetBodyReadTimeout(timeout time.Duration, override bool) OperationHandler

SetBodyReadTimeout creates an OperationHandler that sets operation`s BodyReadTimeout field. If override is `false`, it will not override existing non-zero value.

func SetDeprecated

func SetDeprecated(deprecated bool, override bool) OperationHandler

SetDeprecated creates an OperationHandler that sets operation`s Deprecated field. If override is `false`, it will not override existing `true` value.

func SetDescription

func SetDescription(description string, override bool) OperationHandler

SetDescription creates an OperationHandler that sets the Description field of an operation If override is `false`, it will not override the existing description.

func SetExtensionsKey

func SetExtensionsKey(key string, value any, override bool) OperationHandler

SetExtensionsKey creates an OperationHandler that adds a key to the operation`s Extensions field. If override is `false`, it will not override existing key.

func SetExternalDocs

func SetExternalDocs(externalDocs *huma.ExternalDocs, override bool) OperationHandler

SetExternalDocs returns an OperationHandler that sets ExternalDocs field of an operation. If override is `false` and the operation already has ExternalDocs, it will not be overridden.

func SetMaxBodyBytes

func SetMaxBodyBytes(n int64, override bool) OperationHandler

SetMaxBodyBytes creates an OperationHandler that sets the operation's MaxBodyBytes field to the given value. If override is `false`, it will not override existing non-zero MaxBodyBytes.

func SetMetadataKey

func SetMetadataKey(key string, value any, override bool) OperationHandler

SetMetadataKey creates an OperationHandler that sets the metadata key for the operation If override is `false`, it will not override the existing key.

func SetResponse

func SetResponse(statusCode int, response *huma.Response, override bool) OperationHandler

func SetSkipValidateBody

func SetSkipValidateBody(skipValidateBody bool, override bool) OperationHandler

SetSkipValidateBody creates an OperationHandler that sets the SkipValidateBody field on the operation. If override is `false`, it will not override the existing `true` value.

func SetSkipValidateParams

func SetSkipValidateParams(skipValidateParams bool, override bool) OperationHandler

SetSkipValidateParams creates an OperationHandler that sets the SkipValidateParams field on the operation. If override is `false`, it will not override the existing `true` value.

func UpdateOperationID

func UpdateOperationID(
	explicitOpIDBuilder func(*huma.Operation) string,
) OperationHandler

UpdateOperationID creates an OperationHandler that re-generates the OperationID field on the operation. It does not re-generates OperationID if it's empty If OperationID is not explicitly set, it generates it from the path (in the same way as huma does it by default). If OperationID is explicitly set, it will be updated by the provided `explicitOpIDBuilder`. If `explicitOpIDBuilder` is nil, the following approach will be used for operations with explicitly set OperationID: It will take metadata.KeyBasePath as a prefix for the OperationID, turning it into kebab-case and will append it to the metadata.KeyInitOperationID It's used internally by the library after registration of multiple base paths to make OperationID unique for different base paths and normally should not be used directly.