Authentication Example

This example shows how to configure multiple authentication schemes — Bearer tokens, API keys, and OAuth2 — and apply them to different endpoints. Endpoints reference schemes by name in Security, and the schemes are registered on the built spec.

The Full Program

main.go

package main
 
import (
	"fmt"
	"net/http"
 
	openswag "github.com/gopackx/open-swag-go"
	"github.com/gopackx/open-swag-go/pkg/auth"
	"github.com/gopackx/open-swag-go/pkg/spec"
)
 
func main() {
	// --- Build scheme descriptors (used when registering on the spec) ---
	bearerScheme := auth.BearerAuth("JWT access token obtained from /auth/login")
	apiKeyScheme := auth.APIKeyHeader("X-API-Key", "API key for service-to-service calls")
 
	docs := openswag.New(openswag.Config{
		Info: openswag.Info{
			Title:       "Multi-Auth API",
			Version:     "1.0.0",
			Description: "An API demonstrating multiple authentication schemes.",
		},
		Servers: []openswag.Server{
			{URL: "http://localhost:8080"},
		},
	})
 
	docs.AddAll(
		// Public — no auth required
		openswag.Endpoint{
			Method:      "POST",
			Path:        "/auth/login",
			Summary:     "Login",
			Description: "Authenticate with username and password. Returns a JWT.",
			Tags:        []string{"Auth"},
			RequestBody: &openswag.RequestBody{
				Description: "Login credentials",
				ContentType: "application/json",
				Required:    true,
			},
			Responses: openswag.Responses{
				200: {Description: "JWT token"},
				401: {Description: "Invalid credentials"},
			},
		},
		// Bearer auth — standard user endpoints
		openswag.Endpoint{
			Method:   "GET",
			Path:     "/users/me",
			Summary:  "Get current user",
			Tags:     []string{"Users"},
			Security: []string{"bearerAuth"},
			Responses: openswag.Responses{
				200: {Description: "User profile"},
				401: {Description: "Unauthorized"},
			},
		},
		// API key auth — service-to-service
		openswag.Endpoint{
			Method:      "GET",
			Path:        "/internal/health",
			Summary:     "Internal health check",
			Description: "Used by monitoring services. Requires an API key.",
			Tags:        []string{"Internal"},
			Security:    []string{"apiKey"},
			Responses: openswag.Responses{
				200: {Description: "Service healthy"},
				403: {Description: "Invalid API key"},
			},
		},
		// OAuth2 — third-party integrations
		openswag.Endpoint{
			Method:      "GET",
			Path:        "/users",
			Summary:     "List users",
			Description: "Returns all users. Requires the oauth2 scheme.",
			Tags:        []string{"Users"},
			Security:    []string{"oauth2"},
			Responses: openswag.Responses{
				200: {Description: "User list"},
				401: {Description: "Unauthorized"},
				403: {Description: "Insufficient scope"},
			},
		},
		// Multiple schemes — admin endpoints require both bearer AND API key
		openswag.Endpoint{
			Method:      "DELETE",
			Path:        "/users/{id}",
			Summary:     "Delete a user",
			Description: "Permanently removes a user. Requires both a JWT and an API key.",
			Tags:        []string{"Admin"},
			Security:    []string{"bearerAuth", "apiKey"},
			Parameters: []openswag.Parameter{
				{Name: "id", In: "path", Required: true, Description: "User ID", Schema: spec.NewSchema("string")},
			},
			Responses: openswag.Responses{
				204: {Description: "User deleted"},
				401: {Description: "Unauthorized"},
				403: {Description: "Forbidden — missing API key"},
				404: {Description: "User not found"},
			},
		},
	)
 
	// --- Register the security schemes on the built spec ---
	openapi := docs.BuildSpec()
	openapi.AddSecurityScheme("bearerAuth", &spec.SecurityScheme{
		Type:         "http",
		Scheme:       "bearer",
		BearerFormat: "JWT",
		Description:  bearerScheme.Description,
	})
	openapi.AddSecurityScheme("apiKey", &spec.SecurityScheme{
		Type:        "apiKey",
		Name:        apiKeyScheme.Name,
		In:          string(apiKeyScheme.In),
		Description: apiKeyScheme.Description,
	})
	openapi.AddSecurityScheme("oauth2", &spec.SecurityScheme{
		Type:        "oauth2",
		Description: "OAuth2 authorization code flow",
	})
 
	mux := http.NewServeMux()
	docs.Mount(mux, "/docs")
 
	fmt.Println("Multi-Auth API docs at http://localhost:8080/docs")
	http.ListenAndServe(":8080", mux)
}

Key Concepts

Referencing schemes by name

Each endpoint lists the scheme names it requires in Security (a []string). The matching scheme definitions are registered once on the built spec with AddSecurityScheme.

Name	Type	Use case
`bearerAuth`	HTTP Bearer (JWT)	User-facing endpoints
`apiKey`	API Key (header)	Service-to-service calls
`oauth2`	OAuth2	Third-party integrations

Per-endpoint security

Endpoints without a Security field are public (like /auth/login).

Combining multiple schemes

The admin endpoint passes both "bearerAuth" and "apiKey" in Security, so the client must satisfy both — a logical AND.

Run It

go run main.go

Open http://localhost:8080/docs. The docs UI groups endpoints by tag and shows a lock icon on authenticated endpoints.