Auth Package

pkg/auth provides types for defining OpenAPI security schemes, configuring the interactive authentication playground, and persisting credentials.

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

Most users don't need this package directly. The root openswag package exposes higher-level helpers — BearerAuth, APIKeyAuth, BasicAuth, CookieAuth, and Config.Auth — that wire schemes into the spec for you. See the Core Package reference. Reach for pkg/auth only when you need playground configuration or the CredentialStore.

Scheme

Represents a single OpenAPI security scheme.

type Scheme struct {
    Type             SchemeType     // "http", "apiKey", "oauth2", "openIdConnect"
    Description      string         // Human-readable description
    Name             string         // Header/query/cookie name (apiKey schemes)
    In               APIKeyLocation // "header", "query", or "cookie" (apiKey schemes)
    Scheme           string         // "bearer" or "basic" (http schemes)
    BearerFormat     string         // Token format hint, e.g. "JWT"
    Flows            *OAuthFlows    // OAuth2 flow definitions (oauth2 type)
    OpenIDConnectURL string         // Discovery URL (openIdConnect type)
}

SchemeType constants

type SchemeType string
 
const (
    SchemeTypeHTTP   SchemeType = "http"
    SchemeTypeAPIKey SchemeType = "apiKey"
    SchemeTypeOAuth2 SchemeType = "oauth2"
    SchemeTypeOpenID SchemeType = "openIdConnect"
)

APIKeyLocation constants

type APIKeyLocation string
 
const (
    APIKeyInHeader APIKeyLocation = "header"
    APIKeyInQuery  APIKeyLocation = "query"
    APIKeyInCookie APIKeyLocation = "cookie"
)

Constructors

func BearerAuth(description string) Scheme
func BasicAuth(description string) Scheme
func APIKeyAuth(name string, in APIKeyLocation, description string) Scheme
func APIKeyHeader(name, description string) Scheme
func APIKeyQuery(name, description string) Scheme
func CookieAuth(name, description string) Scheme

BearerAuth returns an HTTP scheme with Scheme: "bearer" and BearerFormat: "JWT".
BasicAuth returns an HTTP scheme with Scheme: "basic".
APIKeyAuth returns an API-key scheme; APIKeyHeader / APIKeyQuery are shorthands. CookieAuth is an API-key scheme located in a cookie.

bearer := auth.BearerAuth("JWT authentication")
apiKey := auth.APIKeyHeader("X-API-Key", "API key authentication")

You don't assign schemes on Config. Instead, reference a scheme name in Endpoint.Security, and the matching security scheme is generated automatically when the spec is built. Predefined names are exported from the root package:

openswag.Endpoint{
    Method:   "GET",
    Path:     "/me",
    Security: []string{openswag.SecurityBearerAuth}, // "bearerAuth"
    // ...
}

To register a custom scheme, prefer the root-package Config.Auth field — that's both shorter and survives a docs.BuildSpec() rebuild:

docs := openswag.New(openswag.Config{
    Info: openswag.Info{Title: "Secure API", Version: "1.0.0"},
    Auth: openswag.AuthConfig{
        Schemes: []openswag.AuthScheme{
            openswag.BearerAuth(openswag.SecurityBearerAuth),
            openswag.APIKeyAuth("apiKey", "X-API-Key"),
        },
    },
})

Names listed in Endpoint.Security that match neither a Security* constant nor an entry in Config.Auth.Schemes are intentionally omitted from the generated spec. Earlier versions silently coerced them to http-bearer, which masked typos in custom scheme names.

If you really need to mutate the spec after the fact, AddSecurityScheme is still available:

openapi := docs.BuildSpec()
openapi.AddSecurityScheme("bearerAuth", &spec.SecurityScheme{
    Type:         "http",
    Scheme:       "bearer",
    BearerFormat: "JWT",
    Description:  auth.BearerAuth("JWT authentication").Description,
})

OAuthFlows

Defines OAuth2 flow configurations for an oauth2 scheme.

type OAuthFlows struct {
    Implicit          *OAuthFlow
    Password          *OAuthFlow
    ClientCredentials *OAuthFlow
    AuthorizationCode *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.

type PlaygroundConfig struct {
    Enabled            bool              // Enable the playground
    DefaultScheme      string            // Pre-selected scheme name
    PersistCredentials bool              // Remember credentials across sessions
    Schemes            map[string]Scheme // Schemes available in the playground
    PrefilledValues    map[string]string // Pre-filled values keyed by scheme
}

Constructor and options

func NewPlayground(opts ...PlaygroundOption) *PlaygroundConfig
 
func WithScheme(name string, scheme Scheme) PlaygroundOption
func WithDefaultScheme(name string) PlaygroundOption
func WithPersistence(enabled bool) PlaygroundOption
func WithPrefilledValue(key, value string) PlaygroundOption
func Disable() PlaygroundOption

NewPlayground defaults to Enabled: true and PersistCredentials: true.

playground := auth.NewPlayground(
    auth.WithScheme("bearerAuth", auth.BearerAuth("JWT authentication")),
    auth.WithDefaultScheme("bearerAuth"),
    auth.WithPersistence(true),
)

CredentialStore

Persists user-entered credentials. CredentialStore is a struct created with NewCredentialStore.

func NewCredentialStore(config PersistConfig) *CredentialStore
 
func (s *CredentialStore) Set(scheme, value string)
func (s *CredentialStore) Get(scheme string) (string, bool)
func (s *CredentialStore) Delete(scheme string)
func (s *CredentialStore) Clear()
func (s *CredentialStore) ToJSON() (string, error)
func (s *CredentialStore) FromJSON(data string) error
func (s *CredentialStore) GetConfig() PersistConfig

Quick Example

package main
 
import (
    "net/http"
 
    openswag "github.com/gopackx/open-swag-go"
)
 
func main() {
    docs := openswag.New(openswag.Config{
        Info: openswag.Info{Title: "Secure API", Version: "1.0.0"},
        Auth: openswag.AuthConfig{
            PersistCredentials: true,
            Schemes: []openswag.AuthScheme{
                openswag.BearerAuth(openswag.SecurityBearerAuth),
            },
        },
    })
 
    docs.Add(openswag.Endpoint{
        Method:   "GET",
        Path:     "/me",
        Summary:  "Get current user",
        Security: []string{openswag.SecurityBearerAuth},
        Responses: openswag.Responses{
            200: openswag.Response("Current user"),
            401: openswag.Response("Unauthorized"),
        },
    })
 
    mux := http.NewServeMux()
    docs.Mount(mux, "/docs")
    http.ListenAndServe(":8080", mux)
}