Authentication

pkg/auth provides constructors for OpenAPI security schemes. You attach a scheme to an endpoint by referencing its name in Endpoint.Security (a []string); the scheme is registered automatically when the spec is built, or you can register it explicitly with docs.BuildSpec().AddSecurityScheme(...).

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

Scheme constructors

func BearerAuth(description string) auth.Scheme
func BasicAuth(description string) auth.Scheme
func APIKeyAuth(name string, in auth.APIKeyLocation, description string) auth.Scheme
func APIKeyHeader(name, description string) auth.Scheme   // shorthand for in = header
func APIKeyQuery(name, description string) auth.Scheme    // shorthand for in = query
func CookieAuth(name, description string) auth.Scheme

schemes.go

bearer := auth.BearerAuth("JWT access token")
basic  := auth.BasicAuth("Username and password")
apiKey := auth.APIKeyHeader("X-API-Key", "API key in the X-API-Key header")
apiKeyQ := auth.APIKeyQuery("api_key", "API key as a query parameter")
cookie := auth.CookieAuth("session_id", "Session cookie set after login")

Attaching schemes to endpoints

Endpoint.Security holds scheme names (strings). The root package exports constants for the common names:

const (
    SecurityBearerAuth  = "bearerAuth"
    SecurityBasicAuth   = "basicAuth"
    SecurityApiKey      = "apiKeyAuth"
    SecurityApiKeyQuery = "apiKeyQuery"
    SecurityOAuth2      = "oauth2"
)

openswag.Endpoint{
    Method:   "GET",
    Path:     "/users/me",
    Summary:  "Get current user profile",
    Tags:     []string{"Users"},
    Security: []string{openswag.SecurityBearerAuth},
    Responses: openswag.Responses{
        200: {Description: "User profile"},
        401: {Description: "Unauthorized"},
    },
}

Schemes referenced this way are auto-generated in the spec. To control the exact definition (e.g. a custom description or bearer format), register it explicitly:

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

OAuth2

There's no dedicated constructor — build an OAuth2 scheme with the auth.Scheme struct and auth.OAuthFlows / auth.OAuthFlow:

oauth2.go

oauth2 := auth.Scheme{
    Type:        auth.SchemeTypeOAuth2,
    Description: "OAuth2 with authorization code flow",
    Flows: &auth.OAuthFlows{
        AuthorizationCode: &auth.OAuthFlow{
            AuthorizationURL: "https://auth.example.com/authorize",
            TokenURL:         "https://auth.example.com/token",
            Scopes: map[string]string{
                "read:users":  "Read user profiles",
                "write:users": "Create and update users",
            },
        },
        ClientCredentials: &auth.OAuthFlow{
            TokenURL: "https://auth.example.com/token",
            Scopes:   map[string]string{"service": "Service-level access"},
        },
    },
}

Combining multiple schemes

List several names in Security; the client must satisfy all of them (logical AND):

openswag.Endpoint{
    Method:   "POST",
    Path:     "/admin/users",
    Summary:  "Create admin user",
    Tags:     []string{"Admin"},
    Security: []string{openswag.SecurityBearerAuth, openswag.SecurityApiKey},
    Responses: openswag.Responses{
        201: {Description: "Admin user created"},
        401: {Description: "Unauthorized"},
        403: {Description: "Forbidden"},
    },
}

Set the same Security slice on each endpoint that needs protection. (Config has no global security field — apply security per endpoint.)

Authentication

Scheme constructors

Attaching schemes to endpoints

OAuth2

Combining multiple schemes

On this page