Auth Package

pkg/auth provides types for defining OpenAPI security schemes, configuring the interactive authentication playground, and managing credential persistence.

import "github.com/andrianprasetya/open-swag-go/pkg/auth"

Scheme

Represents a single OpenAPI security scheme.

type Scheme struct {
    Name        string     // Unique scheme identifier, e.g. "bearerAuth"
    Type        SchemeType // bearer, basic, apiKey, cookie, oauth2
    Description string     // Human-readable description
    In          string     // Location for apiKey: "header", "query", or "cookie"
    FieldName   string     // Header/query/cookie name for apiKey schemes
    BearerFormat string    // Token format hint, e.g. "JWT"
    Flows       *OAuthFlows // OAuth2 flow definitions (oauth2 type only)
}

SchemeType Constants

type SchemeType string
 
const (
    SchemeBearer SchemeType = "bearer"
    SchemeBasic  SchemeType = "basic"
    SchemeAPIKey SchemeType = "apiKey"
    SchemeCookie SchemeType = "cookie"
    SchemeOAuth2 SchemeType = "oauth2"
)

Constructors

func BearerAuth() Scheme

Returns a pre-configured Bearer token scheme with BearerFormat: "JWT".

func BasicAuth() Scheme

Returns a pre-configured HTTP Basic authentication scheme.

func APIKeyAuth(name, in string) Scheme

Returns an API key scheme. name is the header/query parameter name, in is "header" or "query".

func CookieAuth(cookieName string) Scheme

Returns a cookie-based authentication scheme.

func OAuth2(flows *OAuthFlows) Scheme

Returns an OAuth2 scheme with the given flow configuration.

Usage

schemes := []auth.Scheme{
    auth.BearerAuth(),
    auth.APIKeyAuth("X-API-Key", "header"),
}
 
cfg := openswag.Config{
    // ...
    Security: schemes,
}

OAuthFlows

Defines OAuth2 flow configurations.

type OAuthFlows struct {
    AuthorizationCode *OAuthFlow
    ClientCredentials *OAuthFlow
    Implicit          *OAuthFlow
    Password          *OAuthFlow
}
 
type OAuthFlow struct {
    AuthorizationURL string
    TokenURL         string
    RefreshURL       string
    Scopes           map[string]string // scope name → description
}

PlaygroundConfig

Configures the interactive authentication playground in the docs UI. Users can enter credentials and test authenticated endpoints directly.

type PlaygroundConfig struct {
    Enabled            bool              // Enable the auth playground
    PersistCredentials bool              // Remember credentials across sessions
    DefaultScheme      string            // Pre-selected scheme name
    Store              CredentialStore   // Storage backend for credentials
}

Functional Options

func WithPlayground(opts ...PlaygroundOption) PlaygroundConfig

func EnablePersistence() PlaygroundOption

Enables credential persistence across browser sessions using localStorage.

func WithDefaultScheme(name string) PlaygroundOption

Sets the initially selected authentication scheme.

func WithStore(store CredentialStore) PlaygroundOption

Provides a custom credential storage backend.

Usage

playground := auth.WithPlayground(
    auth.EnablePersistence(),
    auth.WithDefaultScheme("bearerAuth"),
)
 
cfg := openswag.Config{
    // ...
    AuthPlayground: playground,
}

CredentialStore

Interface for persisting user-entered credentials.

type CredentialStore interface {
    Get(scheme string) (string, error)
    Set(scheme string, value string) error
    Delete(scheme string) error
}

The default implementation uses the browser's localStorage. You can provide a custom store for server-side persistence or encrypted storage.

Built-in Stores

func NewLocalStore() CredentialStore

Returns the default localStorage-backed store.

func NewMemoryStore() CredentialStore

Returns an in-memory store that does not persist across page reloads. Useful for testing or high-security environments.

Quick Example

package main
 
import (
    "net/http"
    openswag "github.com/andrianprasetya/open-swag-go"
    "github.com/andrianprasetya/open-swag-go/pkg/auth"
)
 
func main() {
    cfg := openswag.Config{
        Info: openswag.Info{Title: "Secure API", Version: "1.0.0"},
        Security: []auth.Scheme{
            auth.BearerAuth(),
            auth.APIKeyAuth("X-API-Key", "header"),
        },
        AuthPlayground: auth.WithPlayground(
            auth.EnablePersistence(),
            auth.WithDefaultScheme("bearerAuth"),
        ),
    }
 
    endpoints := []openswag.Endpoint{
        {
            Method:   "GET",
            Path:     "/me",
            Summary:  "Get current user",
            Security: []string{"bearerAuth"},
            Responses: []openswag.Response{
                {StatusCode: 200, Description: "Current user", ContentType: "application/json"},
                {StatusCode: 401, Description: "Unauthorized"},
            },
        },
    }
 
    docs := openswag.New(cfg, endpoints...)
    http.Handle("/docs/", docs.Handler())
    http.ListenAndServe(":8080", nil)
}

On this page