API Options

Complete reference for all API-level configuration options (functions passed to New() or MustNew()).

Info Options

WithTitle

func WithTitle(title, version string) Option

Sets the API title and version. Required.

Parameters:

• title - API title.
• version - API version like “1.0.0”.

Example:

openapi.WithTitle("My API", "1.0.0")

WithInfoDescription

func WithInfoDescription(description string) Option

Sets the API description.

Example:

openapi.WithInfoDescription("Comprehensive API for managing users and resources")

WithInfoSummary

func WithInfoSummary(summary string) Option

Sets a short summary for the API. OpenAPI 3.1 only. Generates warning if used with 3.0 target.

Example:

openapi.WithInfoSummary("User Management API")

WithTermsOfService

func WithTermsOfService(url string) Option

Sets the terms of service URL.

Example:

openapi.WithTermsOfService("https://example.com/terms")

WithContact

func WithContact(name, url, email string) Option

Sets contact information.

Parameters:

• name - Contact name
• url - Contact URL
• email - Contact email

Example:

openapi.WithContact("API Support", "https://example.com/support", "support@example.com")

WithLicense

func WithLicense(name, url string) Option

Sets license information.

Parameters:

• name - License name
• url - License URL

Example:

openapi.WithLicense("Apache 2.0", "https://www.apache.org/licenses/LICENSE-2.0.html")

WithLicenseIdentifier

func WithLicenseIdentifier(name, identifier string) Option

Sets license with SPDX identifier. OpenAPI 3.1 only.

Parameters:

• name - License name
• identifier - SPDX license identifier

Example:

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

WithInfoExtension

func WithInfoExtension(key string, value any) Option

Adds a custom extension to the info object.

Parameters:

• key - Extension key (must start with x-)
• value - Extension value

Example:

openapi.WithInfoExtension("x-api-id", "user-service")

Version Options

WithVersion

func WithVersion(version Version) Option

Sets the target OpenAPI version. Default is V30x.

Parameters:

• version - Either V30x or V31x

Example:

openapi.WithVersion(openapi.V31x)

Server Options

WithServer

func WithServer(url, description string) Option

Adds a server configuration.

Parameters:

• url - Server URL
• description - Server description

Example:

openapi.WithServer("https://api.example.com", "Production")
openapi.WithServer("http://localhost:8080", "Development")

WithServerVariable

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

Adds a server variable for URL templating.

Parameters:

• name - Variable name
• defaultValue - Default value
• enumValues - Allowed values
• description - Variable description

Example:

openapi.WithServer("https://{environment}.example.com", "Environment-based"),
openapi.WithServerVariable("environment", "api", 
    []string{"api", "staging", "dev"},
    "Environment to use",
)

Security Scheme Options

WithBearerAuth

func WithBearerAuth(name, description string) Option

Adds Bearer (JWT) authentication scheme.

Parameters:

• name - Security scheme name (used in WithSecurity())
• description - Scheme description

Example:

openapi.WithBearerAuth("bearerAuth", "JWT authentication")

WithAPIKey

func WithAPIKey(name, paramName string, location ParameterLocation, description string) Option

Adds API key authentication scheme.

Parameters:

• name - Security scheme name
• paramName - Parameter name (e.g., “X-API-Key”, “api_key”)
• location - Where the key is located: InHeader, InQuery, or InCookie
• description - Scheme description

Example:

openapi.WithAPIKey("apiKey", "X-API-Key", openapi.InHeader, "API key for authentication")

WithOAuth2

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

Adds OAuth2 authentication scheme.

Parameters:

• name - Security scheme name
• description - Scheme description
• flows - OAuth2 flow configurations

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

WithOpenIDConnect

func WithOpenIDConnect(name, openIDConnectURL, description string) Option

Adds OpenID Connect authentication scheme.

Parameters:

• name - Security scheme name
• openIDConnectURL - OpenID Connect discovery URL
• description - Scheme description

Example:

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

WithDefaultSecurity

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

Sets default security requirement at API level (applies to all operations unless overridden).

Parameters:

• scheme - Security scheme name
• scopes - Optional OAuth2 scopes

Example:

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

Tag Options

WithTag

func WithTag(name, description string) Option

Adds a tag for organizing operations.

Parameters:

• name - Tag name
• description - Tag description

Example:

openapi.WithTag("users", "User management operations")
openapi.WithTag("posts", "Post management operations")

External Documentation

WithExternalDocs

func WithExternalDocs(url, description string) Option

Links to external documentation.

Parameters:

• url - Documentation URL
• description - Documentation description

Example:

openapi.WithExternalDocs("https://docs.example.com", "Full API Documentation")

Validation Options

WithValidation

func WithValidation(enabled bool) Option

Enables or disables specification validation. Default is false.

Parameters:

• enabled - Whether to validate generated specs

Example:

openapi.WithValidation(true) // Enable validation

WithStrictDownlevel

func WithStrictDownlevel(enabled bool) Option

Enables strict downlevel mode. When enabled, using 3.1 features with a 3.0 target causes errors instead of warnings. Default is false.

Parameters:

• enabled - Whether to error on downlevel issues

Example:

openapi.WithStrictDownlevel(true) // Error on 3.1 features with 3.0 target

WithSpecPath

func WithSpecPath(path string) Option

Sets the path where the OpenAPI specification will be served.

Parameters:

• path - URL path for the spec (e.g., “/openapi.json”)

Example:

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

Swagger UI Options

WithSwaggerUI

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

Configures Swagger UI at the specified path.

Parameters:

• path - URL path where Swagger UI is served
• opts - Swagger UI configuration options (see Swagger UI Options)

Example:

openapi.WithSwaggerUI("/docs",
    openapi.WithUIExpansion(openapi.DocExpansionList),
    openapi.WithUITryItOut(true),
)

WithoutSwaggerUI

func WithoutSwaggerUI() Option

Disables Swagger UI.

Example:

openapi.WithoutSwaggerUI()

Extension Options

WithExtension

func WithExtension(key string, value interface{}) Option

Adds a custom x-* extension to the root of the specification.

Parameters:

• key - Extension key (must start with x-)
• value - Extension value (any JSON-serializable type)

Example:

openapi.WithExtension("x-api-version", "v2")
openapi.WithExtension("x-custom-config", map[string]interface{}{
    "feature": "enabled",
    "rate-limit": 100,
})

Next Steps

• See Operation Options for operation-level configuration
• Check Swagger UI Options for UI customization
• Review API Reference for types and methods