option

package
v0.5.1 Latest Latest
Warning

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

 Go to latest Published: May 12, 2026 License: MIT Imports: 13 Imported by: 27

Documentation

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 builds config with defaults and applies options in order.

Example: 

cfg := option.WithOpenAPIConfig(
	option.WithOpenAPIVersion(openapi.Version312),
	option.WithTitle("Payments API"),
	option.WithVersion("1.2.0"),
)

Types

type ContentOption 

type ContentOption func(*openapi.ContentUnit)

ContentOption mutates request/response content generation.

func ContentDefault added in v0.2.0 

func ContentDefault(isDefault ...bool) ContentOption

ContentDefault marks a response as the `default` response.

func ContentDescription added in v0.2.0 

func ContentDescription(description string) ContentOption

ContentDescription sets request-body/response description.

func ContentEncoding added in v0.3.5 

func ContentEncoding(prop, enc string) ContentOption

ContentEncoding sets encoding metadata for a body property.

func ContentExample added in v0.5.0 

func ContentExample(value any) ContentOption

ContentExample sets the media type example value.

func ContentExamples added in v0.5.0 

func ContentExamples(examples map[string]*openapi.Example) ContentOption

ContentExamples sets the media type examples map.

func ContentFormat added in v0.5.0 

func ContentFormat(format string) ContentOption

ContentFormat sets schema format for reflected payload.

func ContentNamedExample added in v0.5.0 

func ContentNamedExample(name string, value any, opts ...ExampleOption) ContentOption

ContentNamedExample adds one named media type example.

func ContentRequired added in v0.5.0 

func ContentRequired(required ...bool) ContentOption

ContentRequired marks request body as required.

func ContentSummary added in v0.5.0 

func ContentSummary(summary string) ContentOption

ContentSummary sets request-body/response summary. It is only valid for OpenAPI 3.2.0.

func ContentType added in v0.2.0 

func ContentType(contentType string) ContentOption

ContentType sets media type, for example `application/json`.

type ExampleOption added in v0.5.0 

type ExampleOption func(*openapi.Example)

ExampleOption mutates an example object.

func ExampleDataValue added in v0.5.0 

func ExampleDataValue(value any) ExampleOption

ExampleDataValue sets example dataValue and clears other value fields. `dataValue` is only valid for OpenAPI 3.2.0.

func ExampleDescription added in v0.5.0 

func ExampleDescription(description string) ExampleOption

ExampleDescription sets example description.

func ExampleExternalValue added in v0.5.0 

func ExampleExternalValue(url string) ExampleOption

ExampleExternalValue sets example externalValue and clears value fields.

func ExampleSerializedValue added in v0.5.0 

func ExampleSerializedValue(value string) ExampleOption

ExampleSerializedValue sets example serializedValue and clears value fields. `serializedValue` is only valid for OpenAPI 3.2.0.

func ExampleSummary added in v0.5.0 

func ExampleSummary(summary string) ExampleOption

ExampleSummary sets example summary.

type GroupConfig added in v0.1.3 

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

GroupConfig stores effective group-level settings.

type GroupOption added in v0.1.3 

type GroupOption func(*GroupConfig)

GroupOption mutates route-group behavior.

func GroupDeprecated added in v0.1.5 

func GroupDeprecated(deprecated ...bool) GroupOption

GroupDeprecated marks all operations in the group deprecated.

func GroupHidden added in v0.2.0 

func GroupHidden(hide ...bool) GroupOption

GroupHidden skips emitting all operations within the group scope.

func GroupSecurity added in v0.1.3 

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

GroupSecurity appends one security requirement to all operations in the group.

func GroupTags added in v0.1.3 

func GroupTags(tags ...string) GroupOption

GroupTags appends tags to all operations in the group.

type OAuthFlowOption added in v0.5.0 

type OAuthFlowOption func(*openapi.OAuthFlow)

OAuthFlowOption mutates an OAuth2 flow.

func OAuthRefreshURL added in v0.5.0 

func OAuthRefreshURL(url string) OAuthFlowOption

OAuthRefreshURL sets OAuth2 flow refreshUrl.

type OpenAPIOption 

type OpenAPIOption func(*openapi.Config)

OpenAPIOption mutates root generator configuration.

func WithCacheAge added in v0.3.3 

func WithCacheAge(cacheAge int) OpenAPIOption

WithCacheAge sets the cache age for OpenAPI specification responses.

func WithComponentCallback added in v0.5.0 

func WithComponentCallback(name string, callback *openapi.Callback) OpenAPIOption

WithComponentCallback registers a reusable callback component.

func WithComponentExample added in v0.5.0 

func WithComponentExample(name string, example *openapi.Example) OpenAPIOption

WithComponentExample registers a reusable example component.

func WithComponentHeader added in v0.5.0 

func WithComponentHeader(name string, header *openapi.Header) OpenAPIOption

WithComponentHeader registers a reusable header component. 

func WithComponentLink(name string, link *openapi.Link) OpenAPIOption

WithComponentLink registers a reusable link component.

func WithComponentMediaType added in v0.5.0 

func WithComponentMediaType(name string, mediaType *openapi.MediaType) OpenAPIOption

WithComponentMediaType registers a reusable media type component. Media type components are only valid for OpenAPI 3.2.0.

func WithComponentParameter added in v0.5.0 

func WithComponentParameter(name string, parameter *openapi.Parameter) OpenAPIOption

WithComponentParameter registers a reusable parameter component.

func WithComponentPathItem added in v0.5.0 

func WithComponentPathItem(name string, pathItem *openapi.PathItem) OpenAPIOption

WithComponentPathItem registers a reusable path item component.

func WithComponentRequestBody added in v0.5.0 

func WithComponentRequestBody(name string, requestBody *openapi.RequestBody) OpenAPIOption

WithComponentRequestBody registers a reusable request body component.

func WithComponentResponse added in v0.5.0 

func WithComponentResponse(name string, response *openapi.Response) OpenAPIOption

WithComponentResponse registers a reusable response component.

func WithComponentSchema added in v0.5.0 

func WithComponentSchema(name string, schema *openapi.Schema) OpenAPIOption

WithComponentSchema registers a reusable schema component.

func WithComponentSecurityScheme added in v0.5.0 

func WithComponentSecurityScheme(name string, scheme *openapi.SecurityScheme) OpenAPIOption

WithComponentSecurityScheme registers a reusable security scheme component.

func WithContact added in v0.1.2 

func WithContact(contact openapi.Contact) OpenAPIOption

WithContact sets `info.contact`.

func WithDebugLogger added in v0.5.1 

func WithDebugLogger() OpenAPIOption

WithDebugLogger enables debug-level logging to stderr using [slog.Default()].

func WithDescription 

func WithDescription(description string) OpenAPIOption

WithDescription sets `info.description`.

func WithDisableDocs added in v0.1.4 

func WithDisableDocs(disable ...bool) OpenAPIOption

func WithDocsPath 

func WithDocsPath(path string) OpenAPIOption

func WithDocument added in v0.5.0 

func WithDocument(fn func(*openapi.Document)) OpenAPIOption

WithDocument applies a low-level mutation after routes and reflected schemas have been added and before validation/serialization.

Example: 

r := spec.NewRouter(
	option.WithDocument(func(doc *openapi.Document) {
		doc.Extensions = map[string]any{"x-service": "billing"}
	}),
)

func WithExternalDocs added in v0.1.2 

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

WithExternalDocs sets root `externalDocs`.

func WithGlobalSecurity added in v0.5.0 

func WithGlobalSecurity(name string, scopes ...string) OpenAPIOption

WithGlobalSecurity appends root security requirements.

func WithInfoSummary added in v0.5.0 

func WithInfoSummary(summary string) OpenAPIOption

WithInfoSummary sets `info.summary`.

func WithJSONSchemaDialect added in v0.5.0 

func WithJSONSchemaDialect(uri string) OpenAPIOption

WithJSONSchemaDialect sets the root `jsonSchemaDialect`. It is only valid for OpenAPI 3.1.x and 3.2.0.

func WithLicense added in v0.1.2 

func WithLicense(license openapi.License) OpenAPIOption

WithLicense sets `info.license`.

func WithLogger added in v0.5.1 

func WithLogger(logger *slog.Logger) OpenAPIOption

WithLogger sets logger used for internal debug logs. Passing nil uses [slog.Default()].

func WithOpenAPIVersion 

func WithOpenAPIVersion(version string) OpenAPIOption

WithOpenAPIVersion sets the OpenAPI document version.

func WithPathParser added in v0.1.4 

func WithPathParser(parser openapi.PathParser) OpenAPIOption

WithPathParser sets a custom route path parser.

func WithRapiDoc added in v0.3.3 

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

WithRapiDoc sets the UI documentation to RapiDoc (CDN mode).

func WithReDoc added in v0.3.3 

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

WithReDoc sets the UI documentation to ReDoc (CDN mode).

func WithReflectorConfig added in v0.1.2 

func WithReflectorConfig(opts ...ReflectorOption) OpenAPIOption

WithReflectorConfig mutates schema reflection settings.

Example: 

r := spec.NewRouter(
	option.WithReflectorConfig(
		option.InlineRefs(),
		option.ParameterTagMapping(openapi.ParameterInPath, "uri"),
	),
)

func WithScalar added in v0.3.3 

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

WithScalar sets the UI documentation to Scalar (CDN mode).

func WithSecurity 

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

WithSecurity registers a reusable named security scheme.

Example: 

r := spec.NewRouter(
	option.WithSecurity(
		"bearerAuth",
		option.SecurityHTTPBearer("bearer"),
	),
	option.WithGlobalSecurity("bearerAuth"),
)

func WithSelf added in v0.5.0 

func WithSelf(self string) OpenAPIOption

WithSelf sets the OpenAPI 3.2.0 `$self` URI reference. It is only valid when `openapi` is `3.2.0`.

func WithServer 

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

WithServer appends a root server and applies server options.

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 (CDN mode).

func WithStripTrailingSlash added in v0.4.1 

func WithStripTrailingSlash(strip ...bool) OpenAPIOption

WithStripTrailingSlash toggles trimming of trailing slashes in route paths.

func WithSwaggerUI added in v0.3.2 

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

WithSwaggerUI sets the UI documentation to Swagger UI (CDN mode).

func WithTag added in v0.5.0 

func WithTag(name string, opts ...TagOption) OpenAPIOption

WithTag appends one root-level tag.

func WithTags added in v0.1.2 

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

WithTags appends root-level tags.

func WithTermsOfService added in v0.2.0 

func WithTermsOfService(terms string) OpenAPIOption

WithTermsOfService sets `info.termsOfService`.

func WithTitle 

func WithTitle(title string) OpenAPIOption

WithTitle sets `info.title`.

func WithUIOption added in v0.4.0 

func WithUIOption(opt specui.Option) OpenAPIOption

WithUIOption sets a custom spec-ui option.

This enables consumers to import only the specific provider package they need, improving linker tree-shaking.

func WithVersion 

func WithVersion(version string) OpenAPIOption

WithVersion sets `info.version`.

type OperationConfig 

type OperationConfig struct {
	Hide         bool
	OperationID  string
	Description  string
	Summary      string
	ExternalDocs *openapi.ExternalDocs
	Deprecated   bool
	Tags         []string
	Security     []OperationSecurityConfig
	Requests     []*openapi.ContentUnit
	Responses    []*openapi.ContentUnit
	Customizers  []func(*openapi.Operation)
}

OperationConfig stores effective operation-level settings.

type OperationOption 

type OperationOption func(*OperationConfig)

OperationOption mutates operation generation behavior.

func CustomizeOperation added in v0.5.0 

func CustomizeOperation(fn func(*openapi.Operation)) OperationOption

CustomizeOperation applies a low-level mutation to the generated operation.

func Deprecated 

func Deprecated(deprecated ...bool) OperationOption

Deprecated marks the operation as deprecated.

func Description 

func Description(description string) OperationOption

Description sets operation description.

func ExternalDocs added in v0.5.0 

func ExternalDocs(url string, description ...string) OperationOption

ExternalDocs sets operation external documentation.

func Hidden added in v0.2.0 

func Hidden(hide ...bool) OperationOption

Hidden skips emitting this operation.

func OperationID added in v0.1.2 

func OperationID(id string) OperationOption

OperationID sets `operationId`.

func Request 

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

Request appends one request content unit.

Example: 

r.Post("/users",
	option.Request(new(CreateUserRequest)),
)

func Response 

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

Response appends one response content unit.

Example: 

r.Get("/users/{id}",
	option.Response(200, new(User)),
	option.Response(404, nil, option.ContentDescription("Not Found")),
)

func Security 

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

Security appends one operation security requirement.

func Summary 

func Summary(summary string) OperationOption

Summary sets operation summary and, when empty, description.

func Tags 

func Tags(tags ...string) OperationOption

Tags appends operation tags.

type OperationSecurityConfig added in v0.1.3 

type OperationSecurityConfig struct {
	Name   string
	Scopes []string
}

OperationSecurityConfig describes one operation security requirement entry.

type ReflectorOption added in v0.1.2 

type ReflectorOption func(*openapi.ReflectorConfig)

ReflectorOption mutates schema reflection behavior.

func InlineRefs added in v0.1.2 

func InlineRefs(inline ...bool) ReflectorOption

InlineRefs toggles inlining referenced schemas.

func InterceptDefName added in v0.5.0 

func InterceptDefName(fn func(t reflect.Type, defaultDefName string) string) ReflectorOption

InterceptDefName sets callback to customize reflected definition names.

func InterceptProp added in v0.5.1 

func InterceptProp(fn openapi.InterceptPropFunc) ReflectorOption

InterceptProp sets callback to intercept property schema generation per field. If a previous hook exists, both are chained: the previous hook runs first, and the new hook runs only if the previous did not return an error.

func InterceptSchema added in v0.5.1 

func InterceptSchema(fn openapi.InterceptSchemaFunc) ReflectorOption

InterceptSchema sets callback to intercept schema generation per type. If a previous hook exists, both are chained: the previous hook runs first. If the previous hook returns stop=true or an error, the next hook is not called.

func ParameterTagMapping added in v0.3.6 

func ParameterTagMapping(in openapi.ParameterIn, sourceTag string) ReflectorOption

ParameterTagMapping overrides tag source for a specific parameter location.

func RequiredPropByValidateTag added in v0.1.2 

func RequiredPropByValidateTag(tags ...string) ReflectorOption

RequiredPropByValidateTag marks properties as required when their validate tag contains "required". Optional args: tags[0] overrides the tag name (default "validate"), tags[1] overrides the separator (default ",").

func StripDefNamePrefix added in v0.1.2 

func StripDefNamePrefix(prefixes ...string) ReflectorOption

StripDefNamePrefix appends prefixes removed from reflected definition names.

func TypeMapping added in v0.1.2 

func TypeMapping(src, dst any) ReflectorOption

TypeMapping maps source type to destination type during reflection.

type SecurityOption 

type SecurityOption func(*securityConfig)

SecurityOption mutates a reusable security scheme definition.

func SecurityAPIKey 

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

SecurityAPIKey configures an `apiKey` security scheme.

Example: 

option.WithSecurity(
	"apiKeyAuth",
	option.SecurityAPIKey("X-API-Key", openapi.SecuritySchemeAPIKeyInHeader),
)

func SecurityDeprecated added in v0.5.0 

func SecurityDeprecated(deprecated ...bool) SecurityOption

SecurityDeprecated marks a security scheme deprecated. It is only valid for OpenAPI 3.2.0.

func SecurityDescription 

func SecurityDescription(description string) SecurityOption

SecurityDescription sets security scheme description.

func SecurityHTTPBearer 

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

SecurityHTTPBearer configures an `http` security scheme.

func SecurityMutualTLS added in v0.5.0 

func SecurityMutualTLS() SecurityOption

SecurityMutualTLS configures a `mutualTLS` security scheme.

func SecurityOAuth2 

func SecurityOAuth2(flows openapi.OAuthFlows) SecurityOption

SecurityOAuth2 configures an `oauth2` security scheme.

func SecurityOAuth2AuthorizationCode added in v0.5.0 

func SecurityOAuth2AuthorizationCode(
	authorizationURL string,
	tokenURL string,
	scopes map[string]string,
	opts ...OAuthFlowOption,
) SecurityOption

SecurityOAuth2AuthorizationCode configures an OAuth2 authorization code flow.

Example: 

option.WithSecurity(
	"oauth2",
	option.SecurityOAuth2AuthorizationCode(
		"https://auth.example.com/oauth/authorize",
		"https://auth.example.com/oauth/token",
		map[string]string{"read": "Read access"},
	),
)

func SecurityOAuth2ClientCredentials added in v0.5.0 

func SecurityOAuth2ClientCredentials(
	tokenURL string,
	scopes map[string]string,
	opts ...OAuthFlowOption,
) SecurityOption

SecurityOAuth2ClientCredentials configures an OAuth2 client credentials flow.

func SecurityOAuth2DeviceAuthorization added in v0.5.0 

func SecurityOAuth2DeviceAuthorization(
	deviceAuthorizationURL string,
	tokenURL string,
	scopes map[string]string,
	opts ...OAuthFlowOption,
) SecurityOption

SecurityOAuth2DeviceAuthorization configures an OAuth2 device authorization flow. It is only valid for OpenAPI 3.2.0.

func SecurityOAuth2Implicit added in v0.5.0 

func SecurityOAuth2Implicit(authorizationURL string, scopes map[string]string, opts ...OAuthFlowOption) SecurityOption

SecurityOAuth2Implicit configures an OAuth2 implicit flow.

func SecurityOAuth2MetadataURL added in v0.5.0 

func SecurityOAuth2MetadataURL(url string) SecurityOption

SecurityOAuth2MetadataURL sets oauth2 metadata discovery URL. It is only valid for OpenAPI 3.2.0 and for `oauth2` security schemes.

func SecurityOAuth2Password added in v0.5.0 

func SecurityOAuth2Password(tokenURL string, scopes map[string]string, opts ...OAuthFlowOption) SecurityOption

SecurityOAuth2Password configures an OAuth2 password flow.

func SecurityOpenIDConnect added in v0.5.0 

func SecurityOpenIDConnect(url string) SecurityOption

SecurityOpenIDConnect configures an `openIdConnect` security scheme.

type ServerOption 

type ServerOption func(*openapi.Server)

ServerOption mutates a server entry.

func ServerDescription 

func ServerDescription(description string) ServerOption

ServerDescription sets server description.

func ServerName added in v0.5.0 

func ServerName(name string) ServerOption

ServerName sets server name. It is only valid for OpenAPI 3.2.0.

func ServerVariables 

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

ServerVariables sets server variables map.

type TagOption added in v0.5.0 

type TagOption func(*openapi.Tag)

TagOption mutates a root-level tag.

func TagDescription added in v0.5.0 

func TagDescription(description string) TagOption

TagDescription sets tag description.

func TagExternalDocs added in v0.5.0 

func TagExternalDocs(url string, description ...string) TagOption

TagExternalDocs sets tag external documentation.

func TagKind added in v0.5.0 

func TagKind(kind string) TagOption

TagKind sets the OpenAPI 3.2.0 tag kind. It is only valid when `openapi` is `3.2.0`.

func TagParent added in v0.5.0 

func TagParent(parent string) TagOption

TagParent sets the OpenAPI 3.2.0 tag parent. It is only valid when `openapi` is `3.2.0`.

func TagSummary added in v0.5.0 

func TagSummary(summary string) TagOption

TagSummary sets tag summary.

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.