option

func WithContentType ¶

func WithContentType(contentType string) ContentOption

WithContentType sets the content type for the OpenAPI content.

func GroupHide ¶ added in v0.1.3

func GroupHide(hide ...bool) GroupOption

GroupHide sets the hide option for the group.

If hide is true, the group will not be included in the OpenAPI specification.

func GroupSecurity ¶ added in v0.1.3

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

GroupSecurity adds security schemes to the group.

It will add security schemes to all routes in the sub-router.

func GroupTags ¶ added in v0.1.3

func GroupTags(tags ...string) GroupOption

GroupTags adds tags to the group.

It will add tags to all routes in the sub-router.

func WithBaseURL ¶

func WithBaseURL(baseURL string) OpenAPIOption

WithBaseURL sets the base URL for the OpenAPI documentation.

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 WithReflectorConfig ¶ added in v0.1.2

func WithReflectorConfig(opts ...ReflectorOption) OpenAPIOption

WithReflectorConfig applies custom configurations to the OpenAPI reflector.

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 WithSwaggerConfig ¶

func WithSwaggerConfig(cfg openapi.SwaggerConfig) OpenAPIOption

WithSwaggerConfig sets the configuration for Swagger UI.

This allows customization of the Swagger UI appearance and behavior.

func WithTags ¶ added in v0.1.2

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

WithTags adds tags to 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.

func Deprecated ¶

func Deprecated(deprecated ...bool) OperationOption

Deprecated marks the operation as deprecated in the OpenAPI documentation.

func Description ¶

func Description(description string) OperationOption

Description sets the description for the OpenAPI operation.

func Hide ¶

func Hide(hide ...bool) OperationOption

Hide marks the operation as hidden in the OpenAPI documentation. This is useful for operations that should not be exposed to the public API.

func OperationID ¶ added in v0.1.2

func OperationID(id string) OperationOption

OperationID sets the operation ID for the OpenAPI operation.

func Request ¶

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

Request adds a request structure to the OpenAPI operation.

func Response ¶

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

Response adds a response structure to the OpenAPI operation.

func Security ¶

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

Security adds security requirements to the OpenAPI operation.

func Summary ¶

func Summary(summary string) OperationOption

Summary sets the summary for the OpenAPI operation.

func Tags ¶

func Tags(tags ...string) OperationOption

Tags adds tags to the OpenAPI operation.

func InlineRefs ¶ added in v0.1.2

func InlineRefs() ReflectorOption

InlineRefs sets whether to inline references in the OpenAPI documentation.

If set to true, references will be inlined instead of being stored in the components section.

func InterceptDefNameFunc ¶ added in v0.1.2

func InterceptDefNameFunc(fn openapi.InterceptDefNameFunc) ReflectorOption

InterceptDefNameFunc sets a function to customize schema definition names.

This function will be called with the type and the default definition name. It should return the desired definition name.

func InterceptPropFunc ¶ added in v0.1.2

func InterceptPropFunc(fn openapi.InterceptPropFunc) ReflectorOption

InterceptPropFunc sets a function to intercept property schema generation.

This function will be called with the parameters needed to generate the property schema.

func InterceptSchemaFunc ¶ added in v0.1.2

func InterceptSchemaFunc(fn openapi.InterceptSchemaFunc) ReflectorOption

InterceptSchemaFunc sets a function to intercept schema generation.

This function will be called with the parameters needed to generate the schema. It can be used to modify the schema before it is added to the OpenAPI specification.

func RequiredPropByValidateTag ¶ added in v0.1.2

func RequiredPropByValidateTag(tags ...string) ReflectorOption

RequiredPropByValidateTag sets a function to mark properties as required based on the "validate" tag.

It checks if the "validate" tag contains "required" and adds the property to the required list.

This is useful for automatically marking properties as required based on validation tags because default it use "required:true" tag.

func RootNullable ¶ added in v0.1.2

func RootNullable() ReflectorOption

RootNullable sets whether to allow root schemas to 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.

If set to true, the root schema will be used as a reference for all schemas.

func StripDefNamePrefix ¶ added in v0.1.2

func StripDefNamePrefix(prefixes ...string) ReflectorOption

StripDefNamePrefix sets prefixes to strip from definition names in the OpenAPI documentation.

func TypeMapping ¶ added in v0.1.2

func TypeMapping(src, dst any) ReflectorOption

TypeMapping adds a type mapping for OpenAPI generation.

Example usage:

type NullString struct {
     sql.NullString
}

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

func SecurityAPIKey ¶

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

SecurityAPIKey creates a security scheme for API key authentication.

Example usage:

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.

func SecurityHTTPBearer ¶

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

SecurityHTTPBearer creates a security scheme for HTTP Bearer authentication.

func SecurityOAuth2 ¶

func SecurityOAuth2(flows openapi.OAuthFlows) SecurityOption

SecurityOAuth2 creates a security scheme for OAuth 2.0 authentication.

func ServerDescription ¶

func ServerDescription(description string) ServerOption

ServerDescription sets the description for an OpenAPI server.

Example usage:

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

func ServerVariables ¶

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

ServerVariables sets the variables for an OpenAPI server.

Example usage:

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