Merge pull request #19 from bdpiprava/improvements

 Enhanced suppport for different option and updated documentation and developer experience features

Author: bdpiprava

.gitignore

@@ -7,3 +7,4 @@ build
 docs/.jekyll-cache
 .bundles
 .claude
+coverage*.txt

.golangci.yml

@@ -49,7 +49,7 @@ linters:
     paths:
       - third_party$
       - builtin$
-      - examples$
+      - ^examples/
 
 formatters:
   enable:
@@ -60,4 +60,4 @@ formatters:
     paths:
       - third_party$
       - builtin$
-      - examples$
+      - ^examples/

Makefile

@@ -1,13 +1,19 @@
 # To run unit tests
 ROOT_DIR := $(shell pwd)
+# Other config
+NO_COLOR=\033[0m
+OK_COLOR=\033[32;01m
+ERROR_COLOR=\033[31;01m
+WARN_COLOR=\033[33;01m
 
 tests:
-	@echo "Running tests"
-	go test -count=1 -race ./...
+	@echo "$(OK_COLOR)==> Running tests...$(NO_COLOR)"
+	@go install gotest.tools/gotestsum@latest
+	@gotestsum --format=testname -- -v -race=1 -coverprofile=coverage_unit.txt -coverpkg=./...
 
 # To generate static files
 generate-doc:
-	@echo "Generating docs"
+	@echo "$(OK_COLOR)==> Generating docs...$(NO_COLOR)"
 	@mkdir -p $(ROOT_DIR)/build/docs
 	go run $(ROOT_DIR)/docs/main.go -generate
 

README.md

@@ -294,6 +294,135 @@ html, err := scalargo.NewV2(
 )
 ```
 
+### 🔐 **Authentication Configuration**
+
+Scalar-Go provides comprehensive authentication support for modern APIs, including API Keys, HTTP Basic/Bearer, and OAuth2 flows.
+
+#### **Enhanced API Key Authentication**
+
+```go
+// Simple API Key (header-based, backward compatible)
+scalargo.WithAuthenticationOpts(
+    scalargo.WithAPIKey("your-api-key"),
+)
+
+// Custom header name
+scalargo.WithAuthenticationOpts(
+    scalargo.WithAPIKey("your-api-key", scalargo.WithAPIKeyName("X-API-Key")),
+)
+
+// Query parameter-based API Key
+scalargo.WithAuthenticationOpts(
+    scalargo.WithAPIKeyQuery("api_key", "your-api-key"),
+)
+
+// Cookie-based API Key
+scalargo.WithAuthenticationOpts(
+    scalargo.WithAPIKeyCookie("session_token", "your-token"),
+)
+```
+
+#### **HTTP Basic & Bearer Authentication**
+
+```go
+// HTTP Basic Auth
+scalargo.WithAuthenticationOpts(
+    scalargo.WithHTTPBasicAuth("username", "password"),
+)
+
+// HTTP Bearer Token
+scalargo.WithAuthenticationOpts(
+    scalargo.WithHTTPBearerToken("your-bearer-token"),
+)
+```
+
+#### **OAuth2 Authentication**
+
+Full OAuth2 support with all standard flows and PKCE.
+
+**Authorization Code Flow (Recommended)**
+```go
+scalargo.WithAuthenticationOpts(
+    scalargo.WithOAuth2AuthorizationCode(
+        "https://auth.example.com/oauth/authorize",
+        "https://auth.example.com/oauth/token",
+        scalargo.WithOAuth2ClientID("my-client-id"),
+        scalargo.WithOAuth2RedirectURI("https://myapp.com/callback"),
+        scalargo.WithOAuth2PKCE(scalargo.PKCES256), // SHA-256 PKCE (recommended)
+        scalargo.WithOAuth2Scopes("read:api", "write:api"),
+    ),
+)
+```
+
+**Client Credentials Flow**
+```go
+scalargo.WithAuthenticationOpts(
+    scalargo.WithOAuth2ClientCredentials(
+        "https://auth.example.com/oauth/token",
+        scalargo.WithOAuth2ClientID("service-account"),
+        scalargo.WithOAuth2ClientSecret("super-secret"),
+    ),
+)
+```
+
+**Advanced OAuth2 Customization**
+```go
+scalargo.WithAuthenticationOpts(
+    scalargo.WithOAuth2AuthorizationCode(
+        "https://auth.example.com/oauth/authorize",
+        "https://auth.example.com/oauth/token",
+        scalargo.WithOAuth2ClientID("my-client"),
+        scalargo.WithOAuth2CustomToken("custom_access_token"), // Custom token field name
+        scalargo.WithOAuth2AdditionalAuthParams(map[string]string{
+            "audience": "https://api.example.com",
+        }),
+        scalargo.WithOAuth2AdditionalTokenParams(map[string]string{
+            "resource": "https://resource.example.com",
+        }),
+        scalargo.WithOAuth2CredentialsLocation(scalargo.OAuth2CredentialsHeader),
+    ),
+)
+```
+
+#### **Multiple Security Schemes**
+
+Configure multiple authentication methods for your API:
+
+```go
+scalargo.WithAuthenticationOpts(
+    // Define multiple security schemes
+    scalargo.WithSecurityScheme("api_key",
+        scalargo.APIKeyScheme("X-API-Key", scalargo.APIKeyLocationHeader, "default-key"),
+    ),
+    scalargo.WithSecurityScheme("bearer_auth",
+        scalargo.BearerScheme("default-token"),
+    ),
+    scalargo.WithSecurityScheme("oauth2",
+        scalargo.OAuth2Scheme(
+            scalargo.OAuth2FlowAuthorizationCode,
+            scalargo.OAuth2Config{
+                AuthorizationURL: "https://auth.example.com/authorize",
+                TokenURL:         "https://auth.example.com/token",
+                ClientID:         "my-client",
+                UsePKCE:          scalargo.PKCES256,
+                SelectedScopes:   []string{"read:api", "write:api"},
+            },
+        ),
+    ),
+    // Set preferred security scheme
+    scalargo.WithPreferredSecurityScheme("bearer_auth"),
+)
+```
+
+**PKCE Modes:**
+- `scalargo.PKCES256` - SHA-256 PKCE (recommended for production)
+- `scalargo.PKCEPlain` - Plain PKCE
+- `scalargo.PKCEDisabled` - Disable PKCE
+
+**OAuth2 Credentials Location:**
+- `scalargo.OAuth2CredentialsHeader` - Send credentials in Authorization header (default)
+- `scalargo.OAuth2CredentialsBody` - Send credentials in request body
+
 ## 🚀 Real-World Examples
 
 ### 🏢 **Enterprise API Documentation**

data/loader-malformed/malformed-api.yml

@@ -0,0 +1,4 @@
+openapi: 3.0.0
+info:
+  title: Malformed Test API
+  version: 1.0.0

data/loader-malformed/schemas/bad-array.yml

@@ -0,0 +1,4 @@
+schemas:
+  - item1
+  - item2
+  - item3

data/loader-malformed/schemas/bad-string.yml

@@ -0,0 +1 @@
+schemas: "not an object, surprise!"

data/loader-multiple-files/api.yaml

@@ -0,0 +1,13 @@
+openapi: "3.0.0"
+info:
+  version: 1.0.0
+  title: Swagger Petstore
+  license:
+    name: MIT
+servers:
+  - url: http://petstore.swagger.io/v1
+tags:
+  - name: pets
+    description: Everything about your Pets
+  - name: store
+    description: Access to Petstore