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

WithTitleIfDefault

func WithTitleIfDefault(title, version string) Option

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 and version when the user has not set a custom title. Option order does not matter; when applied last, it only overwrites default values.

Example (typically used by app when building OpenAPI options):

opts = append(opts, openapi.WithTitleIfDefault(serviceName, serviceVersion))

WithDescription

func WithDescription(description string) Option

Sets the API description (Info object).

Example:

openapi.WithDescription("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")

WithOAuth2AuthorizationCode

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

Adds the OAuth2 authorization code flow to the named scheme. authURL and tokenURL are required; refreshURL is optional. 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"})

WithOAuth2Implicit

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

Adds the OAuth2 implicit flow. authURL is required; refreshURL is optional.

Example:

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

WithOAuth2Password

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

Adds the OAuth2 resource owner password flow. tokenURL is required; refreshURL is optional.

Example:

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

WithOAuth2ClientCredentials

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

Adds the OAuth2 client credentials flow. tokenURL is required; refreshURL is optional.

Example:

openapi.WithOAuth2ClientCredentials("oauth2", "OAuth2 authentication",
    "https://example.com/oauth/token", "",
    map[string]string{"api": "API 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(requirements ...SecurityReq) Option

Sets default security requirements at API level. Use [RequireSecurity] to build each requirement.

Example:

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

RequireSecurity

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

Builds a [SecurityReq] for use with [WithDefaultSecurity] or operation [WithSecurity].

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

WithValidateSpec

func WithValidateSpec(validate bool) Option

Enables or disables JSON Schema validation of the generated spec. Default is false.

Example:

openapi.WithValidateSpec(true)

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