option

func WithContentType ¶

func WithContentType(contentType string) ContentOption

WithContentType sets the content type for the OpenAPI content.

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 GroupHide ¶ added in v0.1.3

func GroupHide(hide ...bool) GroupOption

GroupHide 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.

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.

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

func Hide(hide ...bool) OperationOption

Hide 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.

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 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)))

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.

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"},
        },
    }),
)