Authentication

Security schemes are defined in the root openswag package. You attach a scheme to an endpoint by referencing its name in Endpoint.Security (a []string). The definition comes from Config.Auth.Schemes, from one of the predefined Security* names, or from an explicit docs.BuildSpec().AddSecurityScheme(...) call.

Scheme helpers

func BearerAuth(name string) AuthScheme                    // http + bearer, bearerFormat JWT
func BasicAuth(name string) AuthScheme                     // http + basic
func APIKeyAuth(name, headerName string) AuthScheme        // apiKey in a header
func APIKeyQueryAuth(name, paramName string) AuthScheme    // apiKey in a query parameter
func CookieAuth(name, cookieName string) AuthScheme        // apiKey in a cookie

name is the key under components.securitySchemes and the string you put in Endpoint.Security. Register the schemes on Config.Auth:

schemes.go

docs := openswag.New(openswag.Config{
    Info: openswag.Info{Title: "My API", Version: "1.0.0"},
    Auth: openswag.AuthConfig{
        Schemes: []openswag.AuthScheme{
            openswag.BearerAuth(openswag.SecurityBearerAuth),
            openswag.BasicAuth(openswag.SecurityBasicAuth),
            openswag.APIKeyAuth("apiKey", "X-API-Key"),
            openswag.APIKeyQueryAuth("apiKeyQuery", "api_key"),
            openswag.CookieAuth("sessionAuth", "session_id"),
        },
    },
})

Each helper returns a plain AuthScheme struct, so you can change a field before registering it:

bearer := openswag.BearerAuth("bearerAuth")
bearer.Description = "JWT access token obtained from POST /auth/login"

Every scheme in Config.Auth.Schemes is written to the spec, even if no endpoint references it. See AuthConfig for the struct fields.

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"
    SecurityCookieAuth  = "cookieAuth"
    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"},
    },
}

When an endpoint references one of these constants and Config.Auth.Schemes has no scheme with that name, a built-in definition is added to the spec (for example SecurityApiKey is an API key in the X-API-Key header). A scheme you register under the same name always wins. A name that is neither registered nor predefined is left out of the spec, so register custom names explicitly.

OAuth2

SecurityOAuth2 resolves to a placeholder authorization-code flow (/oauth2/authorize, /oauth2/token, scopes read and write). AuthScheme has no flow fields, so describe your real flows with spec.SecurityScheme on the built spec:

oauth2.go

import "github.com/gopackx/open-swag-go/pkg/spec"
 
// After all docs.Add / docs.AddAll calls: Add resets the cached spec.
openapi := docs.BuildSpec()
openapi.AddSecurityScheme(openswag.SecurityOAuth2, &spec.SecurityScheme{
    Type:        "oauth2",
    Description: "OAuth2 with authorization code flow",
    Flows: &spec.OAuthFlows{
        AuthorizationCode: &spec.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: &spec.OAuthFlow{
            TokenURL: "https://auth.example.com/token",
            Scopes:   map[string]string{"service": "Service-level access"},
        },
    },
})

docs.SpecJSON() and the mounted openapi.json serve this cached spec, so the override is what clients see.

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

The docs UI shows an authentication panel for these schemes automatically; see Auth Playground.

Authentication

Scheme helpers

Attaching schemes to endpoints

OAuth2

Combining multiple schemes

On this page