openapi

func MustNew ¶

func MustNew(opts ...Option) *API

MustNew creates a new OpenAPI API and panics if validation fails.

This is a convenience wrapper around New for use in package initialization or when configuration errors should cause immediate failure.

Example:

api := openapi.MustNew(
    openapi.WithTitle("My API", "1.0.0"),
    openapi.WithDescription("API description"),
)

package main

import (
	"fmt"

	"rivaas.dev/openapi"
)

func main() {
	api := openapi.MustNew(
		openapi.WithTitle("My API", "1.0.0"),
		openapi.WithSwaggerUI("/docs"),
	)

	fmt.Printf("UI enabled: %v\n", api.ServeUI)
}

Output:

UI enabled: true

func New ¶

func New(opts ...Option) (*API, error)

New creates a new OpenAPI API with the given options.

It applies default values and validates the configuration. Returns an error if validation fails (e.g., missing title or version). Use API.Validate to check validation rules.

Example:

api, err := openapi.New(
    openapi.WithTitle("My API", "1.0.0"),
    openapi.WithDescription("API description"),
    openapi.WithBearerAuth("bearerAuth", "JWT authentication"),
)
if err != nil {
    log.Fatal(err)
}

package main

import (
	"fmt"

	"rivaas.dev/openapi"
)

func main() {
	api, err := openapi.New(
		openapi.WithTitle("My API", "1.0.0"),
		openapi.WithInfoDescription("API for managing users"),
		openapi.WithServer("http://localhost:8080", "Local development"),
	)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	fmt.Printf("Title: %s, Version: %s\n", api.Info.Title, api.Info.Version)
}

Output:

Title: My API, Version: 1.0.0

func ExternalExample ¶ added in v0.2.0

func ExternalExample(name, url string, opts ...ExampleOption) Example

ExternalExample creates a named example pointing to an external URL.

Use this for:

• Large examples that would bloat the spec
• Examples in formats that can't be embedded (XML, binary)
• Shared examples across multiple specs

Parameters:

• name: Unique identifier
• url: URL pointing to the example content
• opts: Optional configuration (summary, description)

Usage:

openapi.ExternalExample("large-response", "https://api.example.com/examples/large.json")

openapi.ExternalExample("xml-example", "https://api.example.com/examples/user.xml",
    openapi.WithExampleSummary("XML format response"),
)

func NewExample ¶ added in v0.2.0

func NewExample(name string, value any, opts ...ExampleOption) Example

NewExample creates a named example with an inline value. Note: This is named NewExample instead of Example to avoid a naming conflict with the Example type. Go does not allow a type and function with the same name in the same package.

Parameters:

• name: Unique identifier (used as key in OpenAPI examples map)
• value: The example value (serialized to JSON in spec)
• opts: Optional configuration (summary, description)

Usage:

openapi.NewExample("success", UserResponse{ID: 123, Name: "John"})

openapi.NewExample("admin", UserResponse{ID: 1, Role: "admin"},
    openapi.WithExampleSummary("Admin user response"),
)

func WithExampleDescription ¶ added in v0.2.0

func WithExampleDescription(description string) ExampleOption

WithExampleDescription sets a detailed description for the example. CommonMark syntax is supported for rich text formatting.

Usage:

openapi.NewExample("success", data,
    openapi.WithExampleDescription("Returns when the user ID exists and is active."),
)

func WithExampleSummary ¶ added in v0.2.0

func WithExampleSummary(summary string) ExampleOption

WithExampleSummary sets a short description for the example. This appears as the example title in Swagger UI.

Usage:

openapi.NewExample("success", data,
    openapi.WithExampleSummary("Successful response"),
)

func DELETE ¶ added in v0.4.0

func DELETE(path string, opts ...OperationOption) Operation

DELETE creates an Operation for a DELETE request.

Example:

openapi.DELETE("/users/:id",
    openapi.WithSummary("Delete user"),
    openapi.WithResponse(204, nil),
)

package main

import (
	"fmt"
	"net/http"

	"rivaas.dev/openapi"
)

func main() {
	op := openapi.DELETE("/users/:id",
		openapi.WithSummary("Delete user"),
		openapi.WithResponse(http.StatusNoContent, nil),
	)

	fmt.Printf("Method: %s, Path: %s\n", op.Method, op.Path)
}

Output:

Method: DELETE, Path: /users/:id

func GET ¶ added in v0.4.0

func GET(path string, opts ...OperationOption) Operation

GET creates an Operation for a GET request.

Example:

openapi.GET("/users/:id",
    openapi.WithSummary("Get user"),
    openapi.WithResponse(200, User{}),
)

package main

import (
	"fmt"
	"net/http"

	"rivaas.dev/openapi"
)

func main() {
	op := openapi.GET("/users/:id",
		openapi.WithSummary("Get user"),
		openapi.WithDescription("Retrieves a user by ID"),
		openapi.WithResponse(http.StatusOK, User{}),
	)

	fmt.Printf("Method: %s, Path: %s\n", op.Method, op.Path)
}

// User is an example type for documentation.
type User struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

Output:

Method: GET, Path: /users/:id

func HEAD ¶ added in v0.4.0

func HEAD(path string, opts ...OperationOption) Operation

HEAD creates an Operation for a HEAD request.

Example:

openapi.HEAD("/users/:id",
    openapi.WithSummary("Check user exists"),
)

func OPTIONS ¶ added in v0.4.0

func OPTIONS(path string, opts ...OperationOption) Operation

OPTIONS creates an Operation for an OPTIONS request.

Example:

openapi.OPTIONS("/users",
    openapi.WithSummary("Get supported methods"),
)

func Op ¶ added in v0.4.0

func Op(method, path string, opts ...OperationOption) Operation

Op creates an Operation with a custom HTTP method. Prefer using the method-specific constructors (GET, POST, etc.) when possible.

Example:

openapi.Op("CUSTOM", "/resource",
    openapi.WithSummary("Custom operation"),
)

func PATCH ¶ added in v0.4.0

func PATCH(path string, opts ...OperationOption) Operation

PATCH creates an Operation for a PATCH request.

Example:

openapi.PATCH("/users/:id",
    openapi.WithSummary("Partially update user"),
    openapi.WithRequest(PatchUserRequest{}),
    openapi.WithResponse(200, User{}),
)

func POST ¶ added in v0.4.0

func POST(path string, opts ...OperationOption) Operation

POST creates an Operation for a POST request.

Example:

openapi.POST("/users",
    openapi.WithSummary("Create user"),
    openapi.WithRequest(CreateUserRequest{}),
    openapi.WithResponse(201, User{}),
)

package main

import (
	"fmt"
	"net/http"

	"rivaas.dev/openapi"
)

func main() {
	op := openapi.POST("/users",
		openapi.WithSummary("Create user"),
		openapi.WithRequest(CreateUserRequest{}),
		openapi.WithResponse(http.StatusCreated, User{}),
	)

	fmt.Printf("Method: %s, Path: %s\n", op.Method, op.Path)
}

// User is an example type for documentation.
type User struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

// CreateUserRequest is an example request type.
type CreateUserRequest struct {
	Name  string `json:"name"`
	Email string `json:"email"`
}

Output:

Method: POST, Path: /users

func PUT ¶ added in v0.4.0

func PUT(path string, opts ...OperationOption) Operation

PUT creates an Operation for a PUT request.

Example:

openapi.PUT("/users/:id",
    openapi.WithSummary("Update user"),
    openapi.WithRequest(UpdateUserRequest{}),
    openapi.WithResponse(200, User{}),
)

func TRACE ¶ added in v0.4.0

func TRACE(path string, opts ...OperationOption) Operation

TRACE creates an Operation for a TRACE request.

Example:

openapi.TRACE("/users/:id",
    openapi.WithSummary("Trace request"),
)

func WithConsumes ¶ added in v0.4.0

func WithConsumes(contentTypes ...string) OperationOption

WithConsumes sets the content types that this operation accepts.

Example:

openapi.POST("/users",
    openapi.WithConsumes("application/xml", "application/json"),
)

func WithDeprecated ¶ added in v0.4.0

func WithDeprecated() OperationOption

WithDeprecated marks the operation as deprecated.

Example:

openapi.GET("/old-endpoint",
    openapi.WithDeprecated(),
)

package main

import (
	"fmt"

	"rivaas.dev/openapi"
)

func main() {
	op := openapi.GET("/old-endpoint",
		openapi.WithSummary("Old endpoint"),
		openapi.WithDeprecated(),
	)

	fmt.Printf("Method: %s, Path: %s\n", op.Method, op.Path)
}

Output:

Method: GET, Path: /old-endpoint

func WithDescription ¶

func WithDescription(s string) OperationOption

WithDescription sets the operation description.

Example:

openapi.GET("/users/:id",
    openapi.WithDescription("Retrieves a user by their unique identifier"),
)

func WithOperationExtension ¶ added in v0.4.0

func WithOperationExtension(key string, value any) OperationOption

WithOperationExtension adds a specification extension to the operation.

Extension keys MUST start with "x-". In OpenAPI 3.1.x, keys starting with "x-oai-" or "x-oas-" are reserved for the OpenAPI Initiative.

Example:

openapi.GET("/users/:id",
    openapi.WithOperationExtension("x-rate-limit", 100),
    openapi.WithOperationExtension("x-internal", true),
)

func WithOperationID ¶ added in v0.4.0

func WithOperationID(id string) OperationOption

WithOperationID sets a custom operation ID.

Example:

openapi.GET("/users/:id",
    openapi.WithOperationID("getUserById"),
)

func WithOptions ¶ added in v0.4.0

func WithOptions(opts ...OperationOption) OperationOption

WithOptions composes multiple OperationOptions into a single option.

This enables creating reusable option sets for common patterns across operations. Options are applied in the order they are provided, with later options potentially overriding values set by earlier options.

Example:

// Define reusable option sets
var (
    CommonErrors = openapi.WithOptions(
        openapi.WithResponse(400, Error{}),
        openapi.WithResponse(401, Error{}),
        openapi.WithResponse(500, Error{}),
    )

    AuthRequired = openapi.WithOptions(
        openapi.WithSecurity("jwt"),
    )

    UserEndpoint = openapi.WithOptions(
        openapi.WithTags("users"),
        AuthRequired,
        CommonErrors,
    )
)

// Apply composed options to operations
openapi.GET("/users/:id",
    UserEndpoint,
    openapi.WithSummary("Get user"),
    openapi.WithResponse(200, User{}),
)

openapi.POST("/users",
    UserEndpoint,
    openapi.WithSummary("Create user"),
    openapi.WithRequest(CreateUser{}),
    openapi.WithResponse(201, User{}),
)

func WithProduces ¶ added in v0.4.0

func WithProduces(contentTypes ...string) OperationOption

WithProduces sets the content types that this operation returns.

Example:

openapi.GET("/users/:id",
    openapi.WithProduces("application/xml", "application/json"),
)

func WithRequest ¶ added in v0.4.0

func WithRequest(req any, examples ...example.Example) OperationOption

WithRequest sets the request type and optionally provides examples.

Example:

openapi.POST("/users",
    openapi.WithRequest(CreateUserRequest{}),
)

package main

import (
	"fmt"

	"rivaas.dev/openapi"
)

// CreateUserRequest is an example request type.
type CreateUserRequest struct {
	Name  string `json:"name"`
	Email string `json:"email"`
}

func main() {
	op := openapi.POST("/users",
		openapi.WithSummary("Create user"),
		openapi.WithRequest(CreateUserRequest{}),
	)

	fmt.Printf("Method: %s, Path: %s\n", op.Method, op.Path)
}

Output:

Method: POST, Path: /users

func WithResponse ¶ added in v0.4.0

func WithResponse(status int, resp any, examples ...example.Example) OperationOption

WithResponse sets the response schema and examples for a status code.

Example:

openapi.GET("/users/:id",
    openapi.WithResponse(200, User{}),
    openapi.WithResponse(404, ErrorResponse{}),
)

package main

import (
	"fmt"

	"rivaas.dev/openapi"
)

// User is an example type for documentation.
type User struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

func main() {
	op := openapi.GET("/users/:id",
		openapi.WithSummary("Get user"),
		openapi.WithResponse(200, User{}),
	)

	fmt.Printf("Method: %s, Path: %s\n", op.Method, op.Path)
}

Output:

Method: GET, Path: /users/:id

func WithSecurity ¶ added in v0.4.0

func WithSecurity(scheme string, scopes ...string) OperationOption

WithSecurity adds a security requirement.

Example:

openapi.GET("/users/:id",
    openapi.WithSecurity("bearerAuth"),
)

openapi.POST("/users",
    openapi.WithSecurity("oauth2", "read:users", "write:users"),
)

package main

import (
	"fmt"

	"rivaas.dev/openapi"
)

func main() {
	op := openapi.GET("/users/:id",
		openapi.WithSecurity("bearerAuth"),
		openapi.WithSecurity("oauth2", "read:users", "write:users"),
	)

	fmt.Printf("Method: %s, Path: %s\n", op.Method, op.Path)
}

Output:

Method: GET, Path: /users/:id

func WithSummary ¶

func WithSummary(s string) OperationOption

WithSummary sets the operation summary.

Example:

openapi.GET("/users/:id",
    openapi.WithSummary("Get user by ID"),
)

package main

import (
	"fmt"

	"rivaas.dev/openapi"
)

func main() {
	op := openapi.GET("/users",
		openapi.WithSummary("List all users"),
	)

	fmt.Printf("Method: %s, Path: %s\n", op.Method, op.Path)
}

Output:

Method: GET, Path: /users

func WithTags ¶ added in v0.4.0

func WithTags(tags ...string) OperationOption

WithTags adds tags to the operation.

Example:

openapi.GET("/users/:id",
    openapi.WithTags("users", "authentication"),
)

package main

import (
	"fmt"

	"rivaas.dev/openapi"
)

func main() {
	op := openapi.GET("/users/:id",
		openapi.WithTags("users", "admin"),
	)

	fmt.Printf("Method: %s, Path: %s\n", op.Method, op.Path)
}

Output:

Method: GET, Path: /users/:id

func WithAPIKey ¶

func WithAPIKey(name, paramName string, in ParameterLocation, desc string) Option

WithAPIKey adds API key authentication scheme.

Parameters:

• name: Scheme name used in security requirements
• paramName: Name of the header/query parameter (e.g., "X-API-Key")
• in: Location of the API key - use InHeader, InQuery, or InCookie
• desc: Description shown in Swagger UI

Example:

openapi.WithAPIKey("apiKey", "X-API-Key", openapi.InHeader, "API key in X-API-Key header")

func WithBearerAuth ¶

func WithBearerAuth(name, desc string) Option

WithBearerAuth adds Bearer (JWT) authentication scheme.

The name is used to reference this scheme in security requirements. The description appears in Swagger UI to help users understand the authentication.

Example:

openapi.WithBearerAuth("bearerAuth", "JWT token authentication. Format: Bearer <token>")

Then use in routes:

app.GET("/protected", handler).Bearer()

func WithContact ¶

func WithContact(name, url, email string) Option

WithContact sets contact information for the API.

All parameters are optional. Empty strings are omitted from the specification.

Example:

openapi.WithContact("API Support", "https://example.com/support", "[email protected]")

func WithDefaultSecurity ¶

func WithDefaultSecurity(scheme string, scopes ...string) Option

WithDefaultSecurity sets default security requirements applied to all operations.

Operations can override this by specifying their own security requirements using RouteWrapper.Security() or RouteWrapper.Bearer().

Example:

// Apply Bearer auth to all operations by default
openapi.WithDefaultSecurity("bearerAuth")

// Apply OAuth with specific scopes
openapi.WithDefaultSecurity("oauth2", "read", "write")

func WithExtension ¶

func WithExtension(key string, value any) Option

WithExtension adds a specification extension to the root OpenAPI specification.

Extension keys MUST start with "x-". In OpenAPI 3.1.x, keys starting with "x-oai-" or "x-oas-" are reserved for the OpenAPI Initiative.

The value can be any valid JSON value (null, primitive, array, or object). Validation of extension keys happens during API.Validate().

Example:

openapi.WithExtension("x-internal-id", "api-v2")
openapi.WithExtension("x-code-samples", []map[string]any{
    {"lang": "curl", "source": "curl https://api.example.com/users"},
})

func WithExternalDocs ¶

func WithExternalDocs(url, description string) Option

WithExternalDocs sets external documentation URL and optional description.

func WithInfoDescription ¶ added in v0.4.0

func WithInfoDescription(desc string) Option

WithInfoDescription sets the API description in the Info object.

The description supports Markdown formatting and appears in the OpenAPI spec and Swagger UI.

Example:

openapi.WithInfoDescription("A RESTful API for managing users and their profiles.")

func WithInfoExtension ¶

func WithInfoExtension(key string, value any) Option

WithInfoExtension adds a specification extension to the Info object.

Extension keys must start with "x-". In OpenAPI 3.1.x, keys starting with "x-oai-" or "x-oas-" are reserved and cannot be used.

Example:

openapi.WithInfoExtension("x-api-category", "public")

func WithInfoSummary ¶ added in v0.4.0

func WithInfoSummary(summary string) Option

WithInfoSummary sets the API summary in the Info object (OpenAPI 3.1+ only). In 3.0 targets, this will be dropped with a warning.

Example:

openapi.WithInfoSummary("User Management API")

func WithLicense ¶

func WithLicense(name, url string) Option

WithLicense sets license information for the API using a URL (OpenAPI 3.0 style).

The name is required. URL is optional. This is mutually exclusive with identifier - use WithLicenseIdentifier for SPDX identifiers. Validation occurs when New() is called.

Example:

openapi.WithLicense("MIT", "https://opensource.org/licenses/MIT")

func WithLicenseIdentifier ¶

func WithLicenseIdentifier(name, identifier string) Option

WithLicenseIdentifier sets license information for the API using an SPDX identifier (OpenAPI 3.1+).

The name is required. Identifier is an SPDX license expression (e.g., "Apache-2.0"). This is mutually exclusive with URL - use WithLicense for URL-based licenses. Validation occurs when New() is called.

Example:

openapi.WithLicenseIdentifier("Apache 2.0", "Apache-2.0")

func WithOAuth2 ¶

func WithOAuth2(name, desc string, flows ...OAuth2Flow) Option

WithOAuth2 adds OAuth2 authentication scheme.

At least one flow must be configured. Use OAuth2Flow to configure each flow type. Multiple flows can be provided to support different OAuth2 flow types.

Example:

openapi.WithOAuth2("oauth2", "OAuth2 authentication",
	openapi.OAuth2Flow{
		Type:             openapi.FlowAuthorizationCode,
		AuthorizationURL: "https://example.com/oauth/authorize",
		TokenURL:         "https://example.com/oauth/token",
		Scopes: map[string]string{
			"read":  "Read access",
			"write": "Write access",
		},
	},
	openapi.OAuth2Flow{
		Type:     openapi.FlowClientCredentials,
		TokenUrl: "https://example.com/oauth/token",
		Scopes:   map[string]string{"read": "Read access"},
	},
)

func WithOpenIDConnect ¶

func WithOpenIDConnect(name, url, desc string) Option

WithOpenIDConnect adds OpenID Connect authentication scheme.

Parameters:

• name: Scheme name used in security requirements
• url: Well-known URL to discover OpenID Connect provider metadata
• desc: Description shown in Swagger UI

Example:

openapi.WithOpenIDConnect("oidc", "https://example.com/.well-known/openid-configuration", "OpenID Connect authentication")

func WithServer ¶

func WithServer(url, desc string) Option

WithServer adds a server URL to the specification.

Multiple servers can be added by calling this option multiple times. The description is optional and helps distinguish between environments.

Example:

openapi.WithServer("https://api.example.com", "Production"),
openapi.WithServer("https://staging-api.example.com", "Staging"),

func WithServerVariable ¶

func WithServerVariable(name, defaultValue string, enum []string, description string) Option

WithServerVariable adds a variable to the last added server for URL template substitution.

The variable name should match a placeholder in the server URL (e.g., {username}). Default is required. Enum and description are optional.

IMPORTANT: WithServerVariable must be called AFTER WithServer. It applies to the most recently added server. Validation occurs when New() is called.

Example:

openapi.WithServer("https://{username}.example.com:{port}/v1", "Multi-tenant API"),
openapi.WithServerVariable("username", "demo", []string{"demo", "prod"}, "User subdomain"),
openapi.WithServerVariable("port", "8443", []string{"8443", "443"}, "Server port"),

func WithSpecPath ¶

func WithSpecPath(path string) Option

WithSpecPath sets the HTTP path where the OpenAPI specification JSON is served.

Default: "/openapi.json"

Example:

openapi.WithSpecPath("/api/openapi.json")

func WithStrictDownlevel ¶

func WithStrictDownlevel(strict bool) Option

WithStrictDownlevel causes projection to error (instead of warn) when 3.1-only features are used with a 3.0 target.

Default: false (warnings only)

Example:

openapi.WithStrictDownlevel(true)

func WithSwaggerUI ¶

func WithSwaggerUI(path string, opts ...UIOption) Option

WithSwaggerUI enables Swagger UI at the given path with optional configuration.

The path parameter specifies where the Swagger UI will be served (e.g., "/docs"). UI options can be provided to customize the appearance and behavior.

Example:

openapi.MustNew(
    openapi.WithTitle("API", "1.0.0"),
    openapi.WithSwaggerUI("/docs",
        openapi.WithUIExpansion(openapi.ExpandList),
        openapi.WithUITryItOut(true),
        openapi.WithUISyntaxTheme(openapi.Monokai),
    ),
)

func WithTag ¶

func WithTag(name, desc string) Option

WithTag adds a tag to the specification.

Tags are used to group operations in Swagger UI. Operations can be assigned tags using RouteWrapper.Tags(). Multiple tags can be added by calling this option multiple times.

Example:

openapi.WithTag("users", "User management operations"),
openapi.WithTag("orders", "Order processing operations"),

func WithTermsOfService ¶

func WithTermsOfService(url string) Option

WithTermsOfService sets the Terms of Service URL/URI.

func WithTitle ¶

func WithTitle(title, version string) Option

WithTitle sets the API title and version.

Both title and version are required. If not set, defaults to "API" and "1.0.0".

Example:

openapi.WithTitle("User Management API", "2.1.0")

func WithValidation ¶ added in v0.4.0

func WithValidation(enabled bool) Option

WithValidation enables or disables JSON Schema validation of the generated OpenAPI spec.

When enabled, Generate() validates the output against the official OpenAPI meta-schema and returns an error if the spec is invalid.

This is useful for:

• Development: Catch spec generation bugs early
• CI/CD: Ensure generated specs are valid before deployment
• Testing: Verify spec correctness in tests

Performance: Adds ~1-5ms overhead per generation. The default is false for backward compatibility. Enable for development and testing to catch errors early.

Default: false

Example:

openapi.WithValidation(false) // Disable for performance

func WithVersion ¶

func WithVersion(version Version) Option

WithVersion sets the target OpenAPI version.

Use V30x or V31x constants. Default: V30x

Example:

openapi.WithVersion(openapi.V31x)

func WithoutSwaggerUI ¶ added in v0.4.0

func WithoutSwaggerUI() Option

WithoutSwaggerUI disables Swagger UI serving.

Example:

openapi.MustNew(
    openapi.WithTitle("API", "1.0.0"),
    openapi.WithoutSwaggerUI(),
)

func WithUIDeepLinking ¶

func WithUIDeepLinking(enabled bool) UIOption

WithUIDeepLinking enables or disables deep linking in Swagger UI.

When enabled, Swagger UI updates the browser URL when operations are expanded, allowing direct linking to specific operations. Default: true.

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUIDeepLinking(true),
)

func WithUIDefaultModelRendering ¶

func WithUIDefaultModelRendering(mode ModelRenderingMode) UIOption

WithUIDefaultModelRendering sets the initial model display mode.

Valid modes:

• ModelRenderingExample: Show example value (default)
• ModelRenderingModel: Show model structure

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUIDefaultModelRendering(openapi.ModelRenderingModel),
)

func WithUIDisplayOperationID ¶

func WithUIDisplayOperationID(show bool) UIOption

WithUIDisplayOperationID shows or hides operation IDs in Swagger UI.

Operation IDs are useful for code generation and API client libraries. Default: false.

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUIDisplayOperationID(true),
)

func WithUIDisplayRequestDuration ¶

func WithUIDisplayRequestDuration(show bool) UIOption

WithUIDisplayRequestDuration shows or hides request duration in Swagger UI.

When enabled, the time taken for "Try it out" requests is displayed. Default: true.

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUIDisplayRequestDuration(true),
)

func WithUIExpansion ¶ added in v0.4.0

func WithUIExpansion(mode DocExpansionMode) UIOption

WithUIExpansion sets the default expansion level for operations and tags.

Valid modes:

• ExpandList: Expand only tags (default)
• ExpandFull: Expand tags and operations
• ExpandNone: Collapse everything

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUIExpansion(openapi.ExpandFull),
)

func WithUIFilter ¶

func WithUIFilter(enabled bool) UIOption

WithUIFilter enables or disables the operation filter/search box.

When enabled, users can filter operations by typing in a search box. Default: true.

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUIFilter(true),
)

func WithUIMaxDisplayedTags ¶

func WithUIMaxDisplayedTags(max int) UIOption

WithUIMaxDisplayedTags limits the number of tags displayed in Swagger UI.

When set to a positive number, only the first N tags are shown. Remaining tags are hidden. Use 0 or negative to show all tags. Default: 0 (show all).

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUIMaxDisplayedTags(10), // Show only first 10 tags
)

func WithUIModelExpandDepth ¶

func WithUIModelExpandDepth(depth int) UIOption

WithUIModelExpandDepth sets the default expansion depth for model example sections.

Controls how many levels of the example value are expanded. Default: 1.

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUIModelExpandDepth(3),
)

func WithUIModelsExpandDepth ¶

func WithUIModelsExpandDepth(depth int) UIOption

WithUIModelsExpandDepth sets the default expansion depth for model schemas.

Depth controls how many levels of nested properties are expanded by default. Use -1 to hide models completely. Default: 1.

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUIModelsExpandDepth(2), // Expand 2 levels deep
)

func WithUIOperationsSorter ¶

func WithUIOperationsSorter(mode OperationsSorterMode) UIOption

WithUIOperationsSorter sets how operations are sorted within tags.

Valid modes:

• OperationsSorterAlpha: Sort alphabetically by path
• OperationsSorterMethod: Sort by HTTP method (GET, POST, etc.)
• OperationsSorterNone: Use server order (no sorting, default)

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUIOperationsSorter(openapi.OperationsSorterAlpha),
)

func WithUIPersistAuth ¶

func WithUIPersistAuth(enabled bool) UIOption

WithUIPersistAuth enables or disables authorization persistence.

When enabled, authorization tokens are persisted in browser storage and automatically included in subsequent requests. Default: true.

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUIPersistAuth(true),
)

func WithUIRequestSnippets ¶

func WithUIRequestSnippets(enabled bool, languages ...RequestSnippetLanguage) UIOption

WithUIRequestSnippets enables or disables code snippet generation.

When enabled, Swagger UI generates code snippets showing how to call the API in various languages (curl, etc.). The languages parameter specifies which snippet generators to include. If not provided, defaults to curl_bash.

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUIRequestSnippets(true, openapi.SnippetCurlBash, openapi.SnippetCurlPowerShell),
)

func WithUIRequestSnippetsExpanded ¶

func WithUIRequestSnippetsExpanded(expanded bool) UIOption

WithUIRequestSnippetsExpanded sets whether request snippets are expanded by default.

When true, code snippets are shown immediately without requiring user interaction. Default: false.

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUIRequestSnippetsExpanded(true),
)

func WithUIShowCommonExtensions ¶

func WithUIShowCommonExtensions(show bool) UIOption

WithUIShowCommonExtensions shows or hides common JSON Schema extensions.

When enabled, displays schema constraints like pattern, maxLength, minLength, etc. in the UI. Default: true.

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUIShowCommonExtensions(true),
)

func WithUIShowExtensions ¶

func WithUIShowExtensions(show bool) UIOption

WithUIShowExtensions shows or hides vendor extensions (x-* fields) in Swagger UI.

Vendor extensions are custom fields prefixed with "x-" in the OpenAPI spec. Default: false.

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUIShowExtensions(true),
)

func WithUISupportedMethods ¶

func WithUISupportedMethods(methods ...HTTPMethod) UIOption

WithUISupportedMethods sets which HTTP methods have "Try it out" enabled.

By default, all standard HTTP methods support "Try it out". Use this option to restrict which methods can be tested interactively in Swagger UI.

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUISupportedMethods(openapi.MethodGet, openapi.MethodPost),
)

func WithUISyntaxHighlight ¶

func WithUISyntaxHighlight(enabled bool) UIOption

WithUISyntaxHighlight enables or disables syntax highlighting in Swagger UI.

When enabled, request/response examples and code snippets are syntax-highlighted using the configured theme. Default: true.

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUISyntaxHighlight(true),
)

func WithUISyntaxTheme ¶

func WithUISyntaxTheme(theme SyntaxTheme) UIOption

WithUISyntaxTheme sets the syntax highlighting theme for code examples.

Available themes: Agate, Arta, Monokai, Nord, Obsidian, TomorrowNight, Idea. Default: Agate.

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUISyntaxTheme(openapi.SyntaxThemeMonokai),
)

func WithUITagsSorter ¶

func WithUITagsSorter(mode TagsSorterMode) UIOption

WithUITagsSorter sets how tags are sorted in Swagger UI.

Valid modes:

• TagsSorterAlpha: Sort tags alphabetically
• TagsSorterNone: Use server order (no sorting, default)

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUITagsSorter(openapi.TagsSorterAlpha),
)

func WithUITryItOut ¶

func WithUITryItOut(enabled bool) UIOption

WithUITryItOut enables or disables "Try it out" functionality by default.

When enabled, the "Try it out" button is automatically expanded for all operations. Default: true.

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUITryItOut(false), // Require users to click "Try it out"
)

func WithUIValidator ¶

func WithUIValidator(url string) UIOption

WithUIValidator sets the OpenAPI specification validator URL.

Swagger UI can validate your OpenAPI spec against a validator service. Options:

• ValidatorLocal ("local"): Validate locally using embedded meta-schema (recommended) No external calls, fast, private, works offline
• ValidatorNone ("none") or "": Disable validation
• URL string: Use an external validator service (e.g., "https://validator.swagger.io/validator")

Default: "" (no validation)

Example:

// Use local validation (recommended)
openapi.WithSwaggerUI("/docs",
    openapi.WithUIValidator(openapi.ValidatorLocal),
)

// Use external validator
openapi.WithSwaggerUI("/docs",
    openapi.WithUIValidator("https://validator.swagger.io/validator"),
)

// Disable validation
openapi.WithSwaggerUI("/docs",
    openapi.WithUIValidator(openapi.ValidatorNone),
)

func WithUIWithCredentials ¶

func WithUIWithCredentials(enabled bool) UIOption

WithUIWithCredentials enables or disables credentials in CORS requests.

When enabled, cookies and authorization headers are included in cross-origin requests. Only enable if your API server is configured to accept credentials. Default: false.

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUIWithCredentials(true),
)