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.WithDescription("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 WithDELETE ¶ added in v0.6.0

func WithDELETE(path string, opts ...OperationOption) (Operation, error)

WithDELETE creates an Operation for a DELETE request.

Example:

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

package main

import (
	"fmt"
	"net/http"

	"rivaas.dev/openapi"
)

func main() {
	op, err := openapi.WithDELETE("/users/:id",
		openapi.WithSummary("Delete user"),
		openapi.WithResponse(http.StatusNoContent, nil),
	)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

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

Output:
Method: DELETE, Path: /users/:id

func WithGET ¶ added in v0.6.0

func WithGET(path string, opts ...OperationOption) (Operation, error)

WithGET creates an Operation for a GET request.

Example:

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

package main

import (
	"fmt"
	"net/http"

	"rivaas.dev/openapi"
)

func main() {
	op, err := openapi.WithGET("/users/:id",
		openapi.WithSummary("Get user"),
		openapi.WithOperationDescription("Retrieves a user by ID"),
		openapi.WithResponse(http.StatusOK, User{}),
	)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	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 WithHEAD ¶ added in v0.6.0

func WithHEAD(path string, opts ...OperationOption) (Operation, error)

WithHEAD creates an Operation for a HEAD request.

Example:

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

func WithOPTIONS ¶ added in v0.6.0

func WithOPTIONS(path string, opts ...OperationOption) (Operation, error)

WithOPTIONS creates an Operation for an OPTIONS request.

Example:

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

func WithOp ¶ added in v0.6.0

func WithOp(method, path string, opts ...OperationOption) (Operation, error)

WithOp creates an Operation with a custom HTTP method. Prefer WithGET, WithPOST, etc. when possible.

Example:

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

func WithPATCH ¶ added in v0.6.0

func WithPATCH(path string, opts ...OperationOption) (Operation, error)

WithPATCH creates an Operation for a PATCH request.

Example:

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

func WithPOST ¶ added in v0.6.0

func WithPOST(path string, opts ...OperationOption) (Operation, error)

WithPOST creates an Operation for a POST request.

Example:

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

package main

import (
	"fmt"
	"net/http"

	"rivaas.dev/openapi"
)

func main() {
	op, err := openapi.WithPOST("/users",
		openapi.WithSummary("Create user"),
		openapi.WithRequest(CreateUserRequest{}),
		openapi.WithResponse(http.StatusCreated, User{}),
	)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	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 WithPUT ¶ added in v0.6.0

func WithPUT(path string, opts ...OperationOption) (Operation, error)

WithPUT creates an Operation for a PUT request.

Example:

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

func WithTRACE ¶ added in v0.6.0

func WithTRACE(path string, opts ...OperationOption) (Operation, error)

WithTRACE creates an Operation for a TRACE request.

Example:

openapi.WithTRACE("/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.WithPOST("/users",
    openapi.WithConsumes("application/xml", "application/json"),
)

func WithDeprecated ¶ added in v0.4.0

func WithDeprecated(deprecated ...bool) OperationOption

WithDeprecated marks the operation as deprecated. WithDeprecated() is shorthand for WithDeprecated(true).

Example:

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

package main

import (
	"fmt"

	"rivaas.dev/openapi"
)

func main() {
	op, err := openapi.WithGET("/old-endpoint",
		openapi.WithSummary("Old endpoint"),
		openapi.WithDeprecated(),
	)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

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

Output:
Method: GET, Path: /old-endpoint

func WithOperationDescription ¶ added in v0.6.0

func WithOperationDescription(s string) OperationOption

WithOperationDescription sets the operation description.

Example:

openapi.WithGET("/users/:id",
    openapi.WithOperationDescription("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.WithGET("/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.WithGET("/users/:id",
    openapi.WithOperationID("getUserById"),
)

func WithOptions ¶ added in v0.4.0

func WithOptions(opts ...OperationOption) (OperationOption, error)

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.

WithOptions returns an error if any element of opts is nil (validation at compose time).

Example:

// Define reusable option sets (check error at init)
CommonErrors, err := openapi.WithOptions(
    openapi.WithResponse(400, Error{}),
    openapi.WithResponse(401, Error{}),
    openapi.WithResponse(500, Error{}),
)
if err != nil {
    // handle err
}
UserEndpoint, err := openapi.WithOptions(
    openapi.WithTags("users"),
    AuthRequired,
    CommonErrors,
)
if err != nil {
    // handle err
}

// Apply composed options to operations
openapi.WithGET("/users/:id",
    UserEndpoint,
    openapi.WithSummary("Get user"),
    openapi.WithResponse(200, User{}),
)
openapi.WithPOST("/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.WithGET("/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.WithPOST("/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, err := openapi.WithPOST("/users",
		openapi.WithSummary("Create user"),
		openapi.WithRequest(CreateUserRequest{}),
	)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	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.WithGET("/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, err := openapi.WithGET("/users/:id",
		openapi.WithSummary("Get user"),
		openapi.WithResponse(200, User{}),
	)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	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.WithGET("/users/:id",
    openapi.WithSecurity("bearerAuth"),
)

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

package main

import (
	"fmt"

	"rivaas.dev/openapi"
)

func main() {
	op, err := openapi.WithGET("/users/:id",
		openapi.WithSecurity("bearerAuth"),
		openapi.WithSecurity("oauth2", "read:users", "write:users"),
	)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	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.WithGET("/users/:id",
    openapi.WithSummary("Get user by ID"),
)

package main

import (
	"fmt"

	"rivaas.dev/openapi"
)

func main() {
	op, err := openapi.WithGET("/users", openapi.WithSummary("List all users"))
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	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.WithGET("/users/:id",
    openapi.WithTags("users", "authentication"),
)

package main

import (
	"fmt"

	"rivaas.dev/openapi"
)

func main() {
	op, err := openapi.WithGET("/users/:id", openapi.WithTags("users", "admin"))
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	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 an 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 a 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", "support@example.com")

func WithDefaultSecurity ¶

func WithDefaultSecurity(requirements ...SecurityReq) Option

WithDefaultSecurity sets default security requirements applied to all operations.

Operations can override this via WithSecurity on the operation.

Example:

openapi.WithDefaultSecurity(openapi.RequireSecurity("bearerAuth"))
openapi.WithDefaultSecurity(openapi.RequireSecurity("oauth2", "read", "write"))

func WithDescription ¶

func WithDescription(desc string) Option

WithDescription sets the API description in the Info object.

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

Example:

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

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 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 WithOAuth2AuthorizationCode ¶ added in v0.6.0

func WithOAuth2AuthorizationCode(name, desc, authURL, tokenURL, refreshURL string, scopes map[string]string) Option

WithOAuth2AuthorizationCode adds the OAuth2 authorization code flow to the named scheme.

authURL and tokenURL are required. refreshURL is optional. scopes maps scope names to descriptions (can be nil or empty). If a scheme with the same name already exists (e.g. from another flow option), the flow is merged into it.

Example:

openapi.WithOAuth2AuthorizationCode("oauth2", "OAuth2 authentication",
    "https://example.com/oauth/authorize", "https://example.com/oauth/token", "https://example.com/oauth/refresh",
    map[string]string{"read": "Read access", "write": "Write access"})

func WithOAuth2ClientCredentials ¶ added in v0.6.0

func WithOAuth2ClientCredentials(name, desc, tokenURL, refreshURL string, scopes map[string]string) Option

WithOAuth2ClientCredentials adds the OAuth2 client credentials flow to the named scheme.

tokenURL is required. refreshURL is optional. scopes maps scope names to descriptions (can be nil or empty).

Example:

openapi.WithOAuth2ClientCredentials("oauth2", "OAuth2 authentication",
    "https://example.com/oauth/token", "",
    map[string]string{"api": "API access"})

func WithOAuth2Implicit ¶ added in v0.6.0

func WithOAuth2Implicit(name, desc, authURL, refreshURL string, scopes map[string]string) Option

WithOAuth2Implicit adds the OAuth2 implicit flow to the named scheme.

authURL is required. refreshURL is optional. scopes maps scope names to descriptions (can be nil or empty).

Example:

openapi.WithOAuth2Implicit("oauth2", "OAuth2 authentication",
    "https://example.com/oauth/authorize", "https://example.com/oauth/refresh",
    map[string]string{"read": "Read access"})

func WithOAuth2Password ¶ added in v0.6.0

func WithOAuth2Password(name, desc, tokenURL, refreshURL string, scopes map[string]string) Option

WithOAuth2Password adds the OAuth2 resource owner password flow to the named scheme.

tokenURL is required. refreshURL is optional. scopes maps scope names to descriptions (can be nil or empty).

Example:

openapi.WithOAuth2Password("oauth2", "OAuth2 authentication",
    "https://example.com/oauth/token", "https://example.com/oauth/refresh",
    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 WithOperations ¶ added in v0.6.0

func WithOperations(ops ...Operation) Option

WithOperations sets the operations included in the API at construction. Can be empty. Operations can also be added after construction via API.AddOperation.

Example:

openapi.MustNew(
    openapi.WithTitle("My API", "1.0.0"),
    openapi.WithOperations(
        openapi.WithGET("/users/:id", openapi.WithSummary("Get user"), openapi.WithResponse(200, User{})),
        openapi.WithPOST("/users", openapi.WithSummary("Create user"), openapi.WithRequest(CreateUserRequest{}), openapi.WithResponse(201, User{})),
    ),
)

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.DocExpansionList),
        openapi.WithUITryItOut(true),
        openapi.WithUISyntaxTheme(openapi.SyntaxThemeMonokai),
    ),
)

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 WithTitleIfDefault ¶ added in v0.6.0

func WithTitleIfDefault(title, version string) Option

WithTitleIfDefault sets the API title and version only if they are still the defaults ("API" and "1.0.0"). Used by the app package to inject service name/version when the user has not set a custom title. Option order does not matter.

Example (typically used by app, not by users directly):

openapi.New(append(userOpts, openapi.WithTitleIfDefault(serviceName, serviceVersion))...)

func WithValidateSpec ¶ added in v0.6.0

func WithValidateSpec(validate bool) Option

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

When enabled, Spec() 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. Enable for development and testing to catch errors early.

Default: false

Example:

openapi.WithValidateSpec(true)

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 RequireSecurity ¶ added in v0.6.0

func RequireSecurity(scheme string, scopes ...string) SecurityReq

RequireSecurity builds a SecurityReq for use with WithDefaultSecurity or WithSecurity.

Example:

openapi.WithDefaultSecurity(
    openapi.RequireSecurity("bearerAuth"),
    openapi.RequireSecurity("oauth2", "read", "write"),
)

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:

• DocExpansionList: Expand only tags (default)
• DocExpansionFull: Expand tags and operations
• DocExpansionNone: Collapse everything

Example:

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

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