option

package
v0.3.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 5, 2025 License: MIT Imports: 5 Imported by: 19

Documentation

Overview

Package option provides functional options for configuring OpenAPI generation, including server setup, group settings, operation options, and reflector behavior.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func WithOpenAPIConfig added in v0.1.2 

func WithOpenAPIConfig(opts ...OpenAPIOption) *openapi.Config

WithOpenAPIConfig creates a new OpenAPI configuration with the provided options. It initializes the configuration with default values and applies the provided options.

Types

type ContentOption 

type ContentOption func(cu *openapi.ContentUnit)

ContentOption is a function that modifies the ContentUnit.

func ContentDefault added in v0.2.0 

func ContentDefault(isDefault ...bool) ContentOption

ContentDefault sets whether this content unit is the default response.

func ContentDescription added in v0.2.0 

func ContentDescription(description string) ContentOption

ContentDescription sets the description for the OpenAPI content.

func ContentEncoding added in v0.3.5 

func ContentEncoding(prop, enc string) ContentOption

func ContentType added in v0.2.0 

func ContentType(contentType string) ContentOption

ContentType sets the content type for the OpenAPI content.

type GroupConfig added in v0.1.3 

type GroupConfig struct {
	Tags       []string
	Security   []OperationSecurityConfig
	Deprecated bool
	Hide       bool
}

GroupConfig defines configuration options for a group of routes in an OpenAPI specification.

type GroupOption added in v0.1.3 

type GroupOption func(*GroupConfig)

GroupOption applies a configuration option to a GroupConfig.

func GroupDeprecated added in v0.1.5 

func GroupDeprecated(deprecated ...bool) GroupOption

GroupDeprecated sets whether the group is deprecated.

If true, all routes in the group will be marked as deprecated in the OpenAPI output.

func GroupHidden added in v0.2.0 

func GroupHidden(hidden ...bool) GroupOption

GroupHidden sets whether the group should be hidden.

If true, the group and its routes will be excluded from the OpenAPI output.

func GroupSecurity added in v0.1.3 

func GroupSecurity(securityName string, scopes ...string) GroupOption

GroupSecurity adds a security scheme to the group.

The security scheme will apply to all routes in the sub-router.

func GroupTags added in v0.1.3 

func GroupTags(tags ...string) GroupOption

GroupTags sets one or more tags for the group.

These tags will be added to all routes in the sub-router.

type OpenAPIOption 

type OpenAPIOption func(*openapi.Config)

OpenAPIOption defines a function that applies configuration to an OpenAPI Config.

func WithCacheAge added in v0.3.3 

func WithCacheAge(cacheAge int) OpenAPIOption

WithCacheAge sets the cache age for OpenAPI specification responses.

func WithContact added in v0.1.2 

func WithContact(contact openapi.Contact) OpenAPIOption

WithContact sets the contact information for the OpenAPI documentation.

func WithDebug 

func WithDebug(debug ...bool) OpenAPIOption

WithDebug enables or disables debug logging for OpenAPI operations.

If debug is true, debug logging is enabled, otherwise it is disabled. By default, debug logging is disabled.

func WithDescription 

func WithDescription(description string) OpenAPIOption

WithDescription sets the description for the OpenAPI documentation.

func WithDisableDocs added in v0.1.4 

func WithDisableDocs(disable ...bool) OpenAPIOption

WithDisableDocs disables the OpenAPI documentation.

If set to true, the OpenAPI documentation will not be served at the specified path. By default, this is false, meaning the documentation is enabled.

func WithDocsPath 

func WithDocsPath(path string) OpenAPIOption

WithDocsPath sets the path for the OpenAPI documentation.

This is the path where the OpenAPI documentation will be served. The default path is "/docs".

func WithExternalDocs added in v0.1.2 

func WithExternalDocs(url string, description ...string) OpenAPIOption

WithExternalDocs sets the external documentation for the OpenAPI documentation.

func WithLicense added in v0.1.2 

func WithLicense(license openapi.License) OpenAPIOption

WithLicense sets the license information for the OpenAPI documentation.

func WithOpenAPIVersion 

func WithOpenAPIVersion(version string) OpenAPIOption

WithOpenAPIVersion sets the OpenAPI version for the documentation.

The default version is "3.0.3". Supported versions are "3.0.3" and "3.1.0".

func WithPathParser added in v0.1.4 

func WithPathParser(parser openapi.PathParser) OpenAPIOption

WithPathParser sets a custom path parser for the OpenAPI documentation.

The parser must convert framework-style paths to OpenAPI-style parameter syntax. For example, a path like "/users/:id" should be converted to "/users/{id}".

Example: 

// myCustomParser implements PathParser and converts ":param" to "{param}".
type myCustomParser struct {
	re *regexp.Regexp
}

// newMyCustomParser creates an instance with a regexp for colon-prefixed params.
func newMyCustomParser() *myCustomParser {
	return &myCustomParser{
		re: regexp.MustCompile(`:([a-zA-Z_][a-zA-Z0-9_]*)`),
	}
}

// Parse replaces ":param" with "{param}" to match OpenAPI path syntax.
func (p *myCustomParser) Parse(path string) (string, error) {
	return p.re.ReplaceAllString(path, "{$1}"), nil
}

// Example usage:
opt := option.WithPathParser(newMyCustomParser())

func WithRapiDoc added in v0.3.3 

func WithRapiDoc(cfg ...config.RapiDoc) OpenAPIOption

WithRapiDoc sets the UI documentation to RapiDoc.

func WithReDoc added in v0.3.3 

func WithReDoc(cfg ...config.ReDoc) OpenAPIOption

WithReDoc sets the UI documentation to ReDoc.

func WithReflectorConfig added in v0.1.2 

func WithReflectorConfig(opts ...ReflectorOption) OpenAPIOption

WithReflectorConfig applies custom configurations to the OpenAPI reflector.

func WithScalar added in v0.3.3 

func WithScalar(cfg ...config.Scalar) OpenAPIOption

WithScalar sets the UI documentation to Scalar.

func WithSecurity 

func WithSecurity(name string, opts ...SecurityOption) OpenAPIOption

WithSecurity adds a security scheme to the OpenAPI documentation.

It can be used to define API key or HTTP Bearer authentication schemes.

func WithServer 

func WithServer(url string, opts ...ServerOption) OpenAPIOption

WithServer adds a server to the OpenAPI documentation.

func WithSpecPath added in v0.3.2 

func WithSpecPath(path string) OpenAPIOption

WithSpecPath sets the path for the OpenAPI specification.

This is the path where the OpenAPI specification will be served. The default is "/docs/openapi.yaml".

func WithStoplightElements added in v0.3.2 

func WithStoplightElements(cfg ...config.StoplightElements) OpenAPIOption

WithStoplightElements sets the UI documentation to Stoplight Elements.

func WithSwaggerUI added in v0.3.2 

func WithSwaggerUI(cfg ...config.SwaggerUI) OpenAPIOption

WithSwaggerUI sets the UI documentation to Swagger UI.

func WithTags added in v0.1.2 

func WithTags(tags ...openapi.Tag) OpenAPIOption

WithTags adds tags to the OpenAPI documentation.

func WithTermsOfService added in v0.2.0 

func WithTermsOfService(terms string) OpenAPIOption

WithTermsOfService sets the terms of service URL for the OpenAPI documentation.

func WithTitle 

func WithTitle(title string) OpenAPIOption

WithTitle sets the title for the OpenAPI documentation.

func WithVersion 

func WithVersion(version string) OpenAPIOption

WithVersion sets the version for the OpenAPI documentation.

type OperationConfig 

type OperationConfig struct {
	Hide        bool
	OperationID string
	Description string
	Summary     string
	Deprecated  bool
	Tags        []string
	Security    []OperationSecurityConfig

	Requests  []*openapi.ContentUnit
	Responses []*openapi.ContentUnit
}

OperationConfig holds configuration for an OpenAPI operation.

type OperationOption 

type OperationOption func(*OperationConfig)

OperationOption applies configuration to an OpenAPI operation.

func Deprecated 

func Deprecated(deprecated ...bool) OperationOption

Deprecated marks the operation as deprecated.

Deprecated operations should not be used by clients.

func Description 

func Description(description string) OperationOption

Description sets the detailed description for the OpenAPI operation.

func Hidden added in v0.2.0 

func Hidden(hide ...bool) OperationOption

Hidden marks the operation as hidden in the OpenAPI documentation.

This is useful for internal or non-public endpoints.

func OperationID added in v0.1.2 

func OperationID(id string) OperationOption

OperationID sets the unique operation ID for the OpenAPI operation.

func Request 

func Request(structure any, options ...ContentOption) OperationOption

Request adds a request body or parameter structure to the OpenAPI operation.

func Response 

func Response(httpStatus int, structure any, options ...ContentOption) OperationOption

Response adds a response for the OpenAPI operation.

The HTTP status code defines which response is described.

func Security 

func Security(securityName string, scopes ...string) OperationOption

Security adds a security requirement to the OpenAPI operation.

Example: 

r.Get("/me",
    option.Security("bearerAuth"),
)

func Summary 

func Summary(summary string) OperationOption

Summary sets a short summary for the OpenAPI operation.

If no description is set, the summary is also used as the description.

func Tags 

func Tags(tags ...string) OperationOption

Tags adds tags to the OpenAPI operation.

Tags help organize operations in the generated documentation.

type OperationSecurityConfig added in v0.1.3 

type OperationSecurityConfig struct {
	Name   string
	Scopes []string
}

OperationSecurityConfig defines a security requirement for an operation.

type ReflectorOption added in v0.1.2 

type ReflectorOption func(*openapi.ReflectorConfig)

ReflectorOption defines a function that modifies the OpenAPI reflector configuration.

func InlineRefs added in v0.1.2 

func InlineRefs() ReflectorOption

InlineRefs sets references to be inlined in the OpenAPI documentation.

When enabled, references will be inlined instead of defined in the components section.

func InterceptDefNameFunc added in v0.1.2 

func InterceptDefNameFunc(fn openapi.InterceptDefNameFunc) ReflectorOption

InterceptDefNameFunc sets a custom function for generating schema definition names.

The provided function is called with the type and the default definition name, and should return the desired name.

func InterceptPropFunc added in v0.1.2 

func InterceptPropFunc(fn openapi.InterceptPropFunc) ReflectorOption

InterceptPropFunc sets a custom function for generating property schemas.

The provided function is called with the parameters for property schema generation.

func InterceptSchemaFunc added in v0.1.2 

func InterceptSchemaFunc(fn openapi.InterceptSchemaFunc) ReflectorOption

InterceptSchemaFunc sets a custom function for intercepting schema generation.

The provided function is called with the schema generation parameters. You can use it to modify schemas before they are added to the OpenAPI output.

func ParameterTagMapping added in v0.3.6 

func ParameterTagMapping(paramIn openapi.ParameterIn, tagName string) ReflectorOption

ParameterTagMapping sets a custom struct tag mapping for parameters of a specific location.

Example: 

option.WithReflectorConfig(option.ParameterTagMapping(openapi.ParameterInPath, "param"))

func RequiredPropByValidateTag added in v0.1.2 

func RequiredPropByValidateTag(tags ...string) ReflectorOption

RequiredPropByValidateTag marks properties as required based on a struct validation tag.

By default, it uses the `validate` tag and looks for the "required" keyword.

You can override the tag name and separator by providing them:

  • First argument: tag name (default "validate")
  • Second argument: separator (default ",")

Example: 

option.WithReflectorConfig(option.RequiredPropByValidateTag())

func RootNullable added in v0.1.2 

func RootNullable() ReflectorOption

RootNullable sets whether root schemas are allowed to be nullable.

When enabled, root schemas can be nullable in the OpenAPI documentation.

func RootRef added in v0.1.2 

func RootRef() ReflectorOption

RootRef sets whether to use a root reference in the OpenAPI documentation.

When enabled, the root schema will be used as a shared reference for all schemas.

func StripDefNamePrefix added in v0.1.2 

func StripDefNamePrefix(prefixes ...string) ReflectorOption

StripDefNamePrefix specifies one or more prefixes to strip from schema definition names.

func TypeMapping added in v0.1.2 

func TypeMapping(src, dst any) ReflectorOption

TypeMapping defines a custom type mapping for OpenAPI generation.

Example: 

type NullString struct {
    sql.NullString
}

option.WithReflectorConfig(option.TypeMapping(NullString{}, new(string)))

type SecurityOption 

type SecurityOption func(*securityConfig)

SecurityOption applies configuration to a securityConfig.

func SecurityAPIKey 

func SecurityAPIKey(name string, in openapi.SecuritySchemeAPIKeyIn) SecurityOption

SecurityAPIKey defines an API key security scheme.

Example: 

option.WithSecurity("apiKey",
    option.SecurityAPIKey("x-api-key", openapi.SecuritySchemeAPIKeyInHeader),
)

func SecurityDescription 

func SecurityDescription(description string) SecurityOption

SecurityDescription sets the description for the security scheme.

If the description is empty, it clears any existing description.

func SecurityHTTPBearer 

func SecurityHTTPBearer(scheme string, bearerFormat ...string) SecurityOption

SecurityHTTPBearer defines an HTTP Bearer security scheme.

Optionally, you can provide a bearer format.

func SecurityOAuth2 

func SecurityOAuth2(flows openapi.OAuthFlows) SecurityOption

SecurityOAuth2 defines an OAuth 2.0 security scheme.

type ServerOption 

type ServerOption func(*openapi.Server)

ServerOption applies configuration to an OpenAPI server.

func ServerDescription 

func ServerDescription(description string) ServerOption

ServerDescription sets the description for an OpenAPI server.

Example: 

option.WithServer("https://api.example.com",
    option.ServerDescription("Production server"),
)

func ServerVariables 

func ServerVariables(variables map[string]openapi.ServerVariable) ServerOption

ServerVariables sets one or more variables for an OpenAPI server.

Example: 

option.WithServer("https://api.example.com/{version}",
    option.ServerVariables(map[string]openapi.ServerVariable{
        "version": {
            Default:     "v1",
            Description: "API version",
            Enum:        []string{"v1", "v2"},
        },
    }),
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.