Auth Playground

The authentication panel in the docs page, where consumers enter a token, API key or credentials before sending requests, is part of the Scalar UI. It appears automatically for every security scheme in the generated spec. Credentials are entered and kept in the browser by Scalar and are only sent with the requests the console makes; open-swag-go never stores them. Every scheme in Config.Auth.Schemes is listed, whether or not an endpoint references it.

What open-swag-go controls

The playground offers exactly the schemes listed under components.securitySchemes, and marks the operations that require them. You control both:

• Endpoint.Security lists the scheme names an endpoint requires (several names mean all of them are required).
• Config.Auth.Schemes defines schemes with the root-package helpers openswag.BearerAuth, openswag.APIKeyAuth, openswag.APIKeyQueryAuth, openswag.BasicAuth and openswag.CookieAuth.
• The Security* constants (SecurityBearerAuth, SecurityBasicAuth, SecurityApiKey, SecurityApiKeyQuery, SecurityCookieAuth, SecurityOAuth2) resolve to built-in scheme definitions when an endpoint references them and no scheme with that name is registered in Config.Auth.Schemes.

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.APIKeyAuth("apiKey", "X-API-Key"),
		},
	},
})
 
docs.Add(openswag.Endpoint{
	Method:   "GET",
	Path:     "/users/me",
	Summary:  "Get current user",
	Security: []string{openswag.SecurityBearerAuth},
	Responses: openswag.Responses{
		200: {Description: "Current user"},
		401: {Description: "Unauthorized"},
	},
})

A name in Endpoint.Security that is neither registered nor one of the Security* constants is left out of the spec, so it does not show up in the playground. See Authentication for every helper and for custom OAuth2 flows.

AuthConfig.PersistCredentials exists but currently has no effect: it is not passed to Scalar. Whether credentials survive a page reload is up to Scalar.

Earlier versions of this page documented a Go package with playground settings (default scheme, prefilled values, persistence). It was never connected to the docs UI and was removed in v1.3.0; its scheme constructors are replaced by the openswag.BearerAuth family in the root package. See the Migration Guide.