tessl/maven-io-swagger--swagger-annotations

Java annotations for defining Swagger API documentation and OpenAPI specification metadata

—

Pending

Overview

Eval results

Files

Security Documentation

Name: tessl/maven-io-swagger--swagger-annotations
Author: tessl

Security annotations for defining authentication and authorization schemes in Swagger specifications. These annotations enable you to document and enforce security requirements for your APIs, supporting OAuth2, API Key, and Basic Authentication patterns.

Capabilities

@Authorization Annotation

Defines authorization scheme usage for operations. References a security definition by name and optionally specifies required OAuth2 scopes.

/**
 * Defines authorization scheme usage
 * Target: METHOD
 * Retention: RUNTIME
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@interface Authorization {
    /**
     * Name of the authorization scheme
     * Must match a key in SecurityDefinition
     * REQUIRED ATTRIBUTE
     */
    String value();
    
    /**
     * OAuth2 scopes required for this authorization
     * Only used with OAuth2 security schemes
     * Empty array means no specific scopes required
     */
    AuthorizationScope[] scopes() default @AuthorizationScope(scope = "", description = "");
}

Usage Examples:

// Basic authorization reference
@ApiOperation(
    value = "Get user profile",
    authorizations = @Authorization(value = "api_key")
)
@GET
@Path("/profile")
public User getUserProfile() {
    // implementation
}

// OAuth2 with specific scopes
@ApiOperation(
    value = "Delete user account",
    authorizations = @Authorization(
        value = "oauth2", 
        scopes = {
            @AuthorizationScope(scope = "user:delete", description = "Delete user accounts"),
            @AuthorizationScope(scope = "admin", description = "Administrative access")
        }
    )
)
@DELETE
@Path("/users/{id}")
public Response deleteUser(@PathParam("id") Long id) {
    // implementation
}

// Multiple authorization schemes (OR relationship)
@ApiOperation(
    value = "Access admin panel",
    authorizations = {
        @Authorization(value = "oauth2", scopes = {
            @AuthorizationScope(scope = "admin", description = "Admin access")
        }),
        @Authorization(value = "admin_key")
    }
)
@GET
@Path("/admin")
public AdminDashboard getAdminDashboard() {
    // implementation
}

@AuthorizationScope Annotation

Describes OAuth2 authorization scope requirements. Used within @Authorization annotations to specify granular permissions.

/**
 * Describes OAuth2 authorization scope
 * Target: METHOD
 * Retention: RUNTIME
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@interface AuthorizationScope {
    /**
     * OAuth2 scope name
     * Should match scope names defined in OAuth2Definition
     * REQUIRED ATTRIBUTE
     */
    String scope();
    
    /**
     * Scope description for documentation
     * Provides human-readable explanation of scope permissions
     * REQUIRED ATTRIBUTE (legacy support)
     */
    String description();
}

Usage Examples:

// Read-only access scope
@AuthorizationScope(scope = "read", description = "Read-only access to resources")

// Write access scope
@AuthorizationScope(scope = "write", description = "Create and modify resources")

// Admin scope with detailed description
@AuthorizationScope(
    scope = "admin", 
    description = "Full administrative access including user management and system configuration"
)

// Resource-specific scopes
@AuthorizationScope(scope = "user:profile:read", description = "Read user profile information")
@AuthorizationScope(scope = "user:profile:write", description = "Modify user profile information")
@AuthorizationScope(scope = "user:delete", description = "Delete user accounts")

@SecurityDefinition Annotation

Aggregates all security definitions for the API. This annotation is used within @SwaggerDefinition to define the available authentication schemes.

/**
 * Aggregates all security definitions
 * Target: ANNOTATION_TYPE
 * Retention: RUNTIME
 */
@Target(ElementType.ANNOTATION_TYPE)
@Retention(RetentionPolicy.RUNTIME)
@interface SecurityDefinition {
    /**
     * OAuth2 security definitions
     * Array of OAuth2 authentication schemes
     */
    OAuth2Definition[] oAuth2Definitions() default {};
    
    /**
     * API Key security definitions
     * Array of API Key authentication schemes
     */
    ApiKeyAuthDefinition[] apiKeyAuthDefinitions() default {};
    
    /** @deprecated Typo in attribute name, use apiKeyAuthDefinitions() instead */
    ApiKeyAuthDefinition[] apiKeyAuthDefintions() default {};
    
    /**
     * Basic Authentication security definitions
     * Array of Basic Auth schemes
     */
    BasicAuthDefinition[] basicAuthDefinitions() default {};
    
    /** @deprecated Typo in attribute name, use basicAuthDefinitions() instead */
    BasicAuthDefinition[] basicAuthDefinions() default {};
}

Usage Examples:

// Complete security definition with multiple schemes
@SwaggerDefinition(
    info = @Info(title = "Secure API", version = "1.0"),
    securityDefinition = @SecurityDefinition(
        oAuth2Definitions = {
            @OAuth2Definition(
                key = "oauth2",
                description = "OAuth2 authentication",
                flow = OAuth2Definition.Flow.AUTHORIZATION_CODE,
                authorizationUrl = "https://auth.example.com/oauth/authorize",
                tokenUrl = "https://auth.example.com/oauth/token",
                scopes = {
                    @Scope(name = "read", description = "Read access"),
                    @Scope(name = "write", description = "Write access"),
                    @Scope(name = "admin", description = "Administrative access")
                }
            )
        },
        apiKeyAuthDefinitions = {
            @ApiKeyAuthDefinition(
                key = "api_key",
                description = "API Key authentication",
                in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
                name = "X-API-Key"
            ),
            @ApiKeyAuthDefinition(
                key = "query_key",
                description = "API Key in query parameter",
                in = ApiKeyAuthDefinition.ApiKeyLocation.QUERY,
                name = "api_key"
            )
        },
        basicAuthDefinitions = {
            @BasicAuthDefinition(
                key = "basic_auth",
                description = "HTTP Basic Authentication"
            )
        }
    )
)
public class SecureApiConfig {
}

// Simple API key only setup
@SwaggerDefinition(
    info = @Info(title = "Simple API", version = "1.0"),
    securityDefinition = @SecurityDefinition(
        apiKeyAuthDefinitions = @ApiKeyAuthDefinition(
            key = "api_key",
            description = "Simple API Key authentication",
            in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
            name = "Authorization"
        )
    )
)
public class SimpleApiConfig {
}

@OAuth2Definition Annotation

Constructs OAuth2 security definitions. Supports all four OAuth2 flows with appropriate URL configurations.

/**
 * Constructs OAuth2 security definition
 * No @Target annotation (used within other annotations)
 * Retention: RUNTIME
 */
@Retention(RetentionPolicy.RUNTIME)
@interface OAuth2Definition {
    /**
     * Security definition key
     * Referenced by @Authorization value
     * REQUIRED ATTRIBUTE
     */
    String key();
    
    /**
     * Security scheme description
     * Human-readable description of the OAuth2 scheme
     */
    String description() default "";
    
    /**
     * OAuth2 flow type
     * Determines which URLs are required
     * REQUIRED ATTRIBUTE
     */
    Flow flow();
    
    /**
     * Authorization URL for implicit/authorization code flows
     * Required for IMPLICIT and ACCESS_CODE flows
     * Ignored for PASSWORD and APPLICATION flows
     */
    String authorizationUrl() default "";
    
    /**
     * Token URL for password/application/authorization code flows
     * Required for PASSWORD, APPLICATION, and ACCESS_CODE flows
     * Ignored for IMPLICIT flow
     */
    String tokenUrl() default "";
    
    /**
     * Available OAuth2 scopes
     * Defines permissions that can be requested
     */
    Scope[] scopes() default {};
    
    /**
     * OAuth2 Flow enumeration
     */
    enum Flow {
        IMPLICIT,        // Implicit grant flow
        ACCESS_CODE,     // Authorization code flow  
        PASSWORD,        // Resource owner password credentials flow
        APPLICATION      // Client credentials flow
    }
}

Usage Examples:

// Authorization Code Flow (most secure for web applications)
@OAuth2Definition(
    key = "oauth2_auth_code",
    description = "OAuth2 Authorization Code Flow",
    flow = OAuth2Definition.Flow.ACCESS_CODE,
    authorizationUrl = "https://auth.example.com/oauth/authorize",
    tokenUrl = "https://auth.example.com/oauth/token",
    scopes = {
        @Scope(name = "read", description = "Read access to resources"),
        @Scope(name = "write", description = "Write access to resources"),
        @Scope(name = "admin", description = "Full administrative access")
    }
)

// Implicit Flow (for client-side applications)
@OAuth2Definition(
    key = "oauth2_implicit",
    description = "OAuth2 Implicit Flow for JavaScript clients",
    flow = OAuth2Definition.Flow.IMPLICIT,
    authorizationUrl = "https://auth.example.com/oauth/authorize",
    scopes = {
        @Scope(name = "profile", description = "Access to user profile"),
        @Scope(name = "email", description = "Access to user email")
    }
)

// Client Credentials Flow (for server-to-server)
@OAuth2Definition(
    key = "oauth2_client_credentials", 
    description = "OAuth2 Client Credentials for service authentication",
    flow = OAuth2Definition.Flow.APPLICATION,
    tokenUrl = "https://auth.example.com/oauth/token",
    scopes = {
        @Scope(name = "service:read", description = "Read access for services"),
        @Scope(name = "service:write", description = "Write access for services")
    }
)

// Password Flow (for trusted applications)
@OAuth2Definition(
    key = "oauth2_password",
    description = "OAuth2 Resource Owner Password Flow",
    flow = OAuth2Definition.Flow.PASSWORD,
    tokenUrl = "https://auth.example.com/oauth/token",
    scopes = {
        @Scope(name = "full_access", description = "Complete access to user resources")
    }
)

@ApiKeyAuthDefinition Annotation

Constructs API Key authentication definitions. Supports keys in headers or query parameters.

/**
 * Constructs API Key authentication definition
 * No @Target annotation (used within other annotations)
 * Retention: RUNTIME
 */
@Retention(RetentionPolicy.RUNTIME)
@interface ApiKeyAuthDefinition {
    /**
     * Security definition key
     * Referenced by @Authorization value
     * REQUIRED ATTRIBUTE
     */
    String key();
    
    /**
     * Security scheme description
     * Human-readable description of the API key scheme
     */
    String description() default "";
    
    /**
     * Key location (header or query parameter)
     * Determines how the API key is transmitted
     * REQUIRED ATTRIBUTE
     */
    ApiKeyLocation in();
    
    /**
     * Header or query parameter name
     * Name of the field containing the API key
     * REQUIRED ATTRIBUTE
     */
    String name();
    
    /**
     * API Key Location enumeration
     */
    enum ApiKeyLocation {
        HEADER("header"),
        QUERY("query");
        
        private final String value;
        
        ApiKeyLocation(String value) {
            this.value = value;
        }
        
        public static ApiKeyLocation forValue(String value) {
            // Returns enum for string value
        }
        
        public String toValue() {
            return value;
        }
    }
}

Usage Examples:

// Standard Authorization header
@ApiKeyAuthDefinition(
    key = "bearer_token",
    description = "Bearer token authentication",
    in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
    name = "Authorization"
)

// Custom header API key
@ApiKeyAuthDefinition(
    key = "api_key_header",
    description = "Custom API key in header",
    in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
    name = "X-API-Key"
)

// Query parameter API key
@ApiKeyAuthDefinition(
    key = "api_key_query",
    description = "API key as query parameter",
    in = ApiKeyAuthDefinition.ApiKeyLocation.QUERY,
    name = "key"
)

// Multiple API key definitions for different use cases
@SecurityDefinition(
    apiKeyAuthDefinitions = {
        @ApiKeyAuthDefinition(
            key = "user_token",
            description = "User authentication token",
            in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
            name = "X-User-Token"
        ),
        @ApiKeyAuthDefinition(
            key = "app_key",
            description = "Application API key",
            in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,  
            name = "X-App-Key"
        ),
        @ApiKeyAuthDefinition(
            key = "legacy_key",
            description = "Legacy API key for backward compatibility",
            in = ApiKeyAuthDefinition.ApiKeyLocation.QUERY,
            name = "api_key"
        )
    }
)

@BasicAuthDefinition Annotation

Constructs Basic Authentication definitions. Represents HTTP Basic Authentication scheme.

/**
 * Constructs Basic Authentication definition
 * No @Target annotation (used within other annotations)
 * Retention: RUNTIME
 */
@Retention(RetentionPolicy.RUNTIME)
@interface BasicAuthDefinition {
    /**
     * Security definition key
     * Referenced by @Authorization value
     * REQUIRED ATTRIBUTE
     */
    String key();
    
    /**
     * Security scheme description
     * Human-readable description of the Basic Auth scheme
     */
    String description() default "";
}

Usage Examples:

// Simple Basic Authentication
@BasicAuthDefinition(
    key = "basic_auth",
    description = "HTTP Basic Authentication"
)

// Basic Auth with detailed description
@BasicAuthDefinition(
    key = "admin_basic",
    description = "Basic Authentication for administrative access - username and password required"
)

// Multiple Basic Auth schemes for different purposes
@SecurityDefinition(
    basicAuthDefinitions = {
        @BasicAuthDefinition(
            key = "user_basic",
            description = "Basic Authentication for regular users"
        ),
        @BasicAuthDefinition(
            key = "admin_basic", 
            description = "Basic Authentication for administrators"
        )
    }
)

// Combined with other authentication methods
@SecurityDefinition(
    basicAuthDefinitions = @BasicAuthDefinition(
        key = "basic_auth",
        description = "Fallback Basic Authentication"
    ),
    apiKeyAuthDefinitions = @ApiKeyAuthDefinition(
        key = "api_key",
        description = "Preferred API Key authentication", 
        in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
        name = "X-API-Key"
    )
)

@Scope Annotation (Enum)

Defines OAuth2 scope within OAuth2Definition. Represents individual permissions that can be granted.

/**
 * Defines OAuth2 scope
 * No @Target annotation (used within other annotations)
 * Retention: RUNTIME
 */
@Retention(RetentionPolicy.RUNTIME)
@interface Scope {
    /**
     * Scope name
     * Unique identifier for the permission scope
     * REQUIRED ATTRIBUTE
     */
    String name();
    
    /**
     * Scope description
     * Human-readable explanation of what the scope grants
     * REQUIRED ATTRIBUTE
     */
    String description();
}

Usage Examples:

// Standard CRUD scopes
@Scope(name = "read", description = "Read access to resources")
@Scope(name = "write", description = "Create and modify resources") 
@Scope(name = "delete", description = "Delete resources")

// Resource-specific scopes
@Scope(name = "user:profile", description = "Access to user profile information")
@Scope(name = "user:settings", description = "Modify user account settings")
@Scope(name = "user:admin", description = "Administrative access to user accounts")

// Fine-grained permission scopes
@Scope(name = "orders:read", description = "View order information")
@Scope(name = "orders:create", description = "Create new orders")
@Scope(name = "orders:cancel", description = "Cancel existing orders")
@Scope(name = "orders:fulfillment", description = "Manage order fulfillment")

// System-level scopes
@Scope(name = "system:config", description = "Access system configuration")
@Scope(name = "system:monitoring", description = "Access monitoring and metrics")
@Scope(name = "system:backup", description = "Perform system backups")

Complex Security Scenarios

Multi-Tier Authentication

// API with multiple authentication options
@SwaggerDefinition(
    info = @Info(title = "Enterprise API", version = "2.0"),
    securityDefinition = @SecurityDefinition(
        oAuth2Definitions = @OAuth2Definition(
            key = "enterprise_oauth",
            description = "Enterprise OAuth2 with comprehensive scopes",
            flow = OAuth2Definition.Flow.ACCESS_CODE,
            authorizationUrl = "https://auth.enterprise.com/oauth/authorize",
            tokenUrl = "https://auth.enterprise.com/oauth/token",
            scopes = {
                @Scope(name = "employee:read", description = "Read employee data"),
                @Scope(name = "employee:write", description = "Modify employee data"),
                @Scope(name = "payroll:read", description = "Access payroll information"),
                @Scope(name = "payroll:process", description = "Process payroll"),
                @Scope(name = "hr:admin", description = "HR administrative functions"),
                @Scope(name = "system:admin", description = "System administration")
            }
        ),
        apiKeyAuthDefinitions = {
            @ApiKeyAuthDefinition(
                key = "service_key",
                description = "Service-to-service authentication",
                in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
                name = "X-Service-Key"
            ),
            @ApiKeyAuthDefinition(
                key = "integration_key",
                description = "Third-party integration key", 
                in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
                name = "X-Integration-Key"
            )
        },
        basicAuthDefinitions = @BasicAuthDefinition(
            key = "emergency_access",
            description = "Emergency access when OAuth is unavailable"
        )
    )
)
public class EnterpriseApiConfig {
}

// Operations with different security requirements
@Api(tags = "employees")
@Path("/employees")
public class EmployeeController {

    @ApiOperation(
        value = "List employees",
        authorizations = {
            @Authorization(value = "enterprise_oauth", scopes = {
                @AuthorizationScope(scope = "employee:read", description = "Read employee data")
            }),
            @Authorization(value = "service_key")
        }
    )
    @GET
    public List<Employee> listEmployees() {
        // Accessible via OAuth with employee:read scope OR service key
    }
    
    @ApiOperation(
        value = "Process payroll",
        authorizations = @Authorization(value = "enterprise_oauth", scopes = {
            @AuthorizationScope(scope = "payroll:process", description = "Process payroll"),
            @AuthorizationScope(scope = "hr:admin", description = "HR admin required for payroll")
        })
    )
    @POST
    @Path("/payroll/process")
    public Response processPayroll() {
        // Requires BOTH payroll:process AND hr:admin scopes
    }
    
    @ApiOperation(
        value = "Emergency employee access",
        authorizations = @Authorization(value = "emergency_access")
    )
    @GET
    @Path("/emergency/{id}")
    public Employee getEmployeeEmergency(@PathParam("id") Long id) {
        // Basic auth only for emergency situations
    }
}

Microservices Security Architecture

// Gateway service security configuration
@SwaggerDefinition(
    info = @Info(title = "API Gateway", version = "1.0"),
    securityDefinition = @SecurityDefinition(
        oAuth2Definitions = {
            @OAuth2Definition(
                key = "user_oauth",
                description = "User authentication flow",
                flow = OAuth2Definition.Flow.AUTHORIZATION_CODE,
                authorizationUrl = "https://auth.company.com/oauth/authorize",
                tokenUrl = "https://auth.company.com/oauth/token", 
                scopes = {
                    @Scope(name = "profile", description = "Basic profile access"),
                    @Scope(name = "email", description = "Email access"),
                    @Scope(name = "premium", description = "Premium features access")
                }
            ),
            @OAuth2Definition(
                key = "service_oauth",
                description = "Service-to-service authentication",
                flow = OAuth2Definition.Flow.APPLICATION,
                tokenUrl = "https://auth.company.com/oauth/token",
                scopes = {
                    @Scope(name = "service:read", description = "Inter-service read access"),
                    @Scope(name = "service:write", description = "Inter-service write access"),
                    @Scope(name = "service:admin", description = "Service administration")
                }
            )
        },
        apiKeyAuthDefinitions = {
            @ApiKeyAuthDefinition(
                key = "gateway_key",
                description = "Gateway bypass key for internal services",
                in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
                name = "X-Gateway-Key"
            ),
            @ApiKeyAuthDefinition(
                key = "webhook_key",
                description = "Webhook authentication key",
                in = ApiKeyAuthDefinition.ApiKeyLocation.QUERY,
                name = "webhook_key"
            )
        }
    )
)
public class GatewayApiConfig {
}

// User-facing endpoints
@Api(tags = "user-api")
@Path("/api/user")
public class UserApiController {
    
    @ApiOperation(
        value = "Get user profile",
        authorizations = @Authorization(value = "user_oauth", scopes = {
            @AuthorizationScope(scope = "profile", description = "Access to user profile")
        })
    )
    @GET
    @Path("/profile")
    public UserProfile getUserProfile() {
        // User OAuth with profile scope
    }
    
    @ApiOperation(
        value = "Access premium features",
        authorizations = @Authorization(value = "user_oauth", scopes = {
            @AuthorizationScope(scope = "premium", description = "Premium features access")
        })
    )
    @GET
    @Path("/premium")
    public PremiumFeatures getPremiumFeatures() {
        // Requires premium scope
    }
}

// Internal service endpoints  
@Api(tags = "internal-api")
@Path("/internal")
public class InternalApiController {
    
    @ApiOperation(
        value = "Service health check",
        authorizations = {
            @Authorization(value = "service_oauth", scopes = {
                @AuthorizationScope(scope = "service:read", description = "Service read access")
            }),
            @Authorization(value = "gateway_key")
        }
    )
    @GET
    @Path("/health")
    public HealthStatus getHealthStatus() {
        // Service OAuth OR gateway key
    }
    
    @ApiOperation(
        value = "Update service configuration", 
        authorizations = @Authorization(value = "service_oauth", scopes = {
            @AuthorizationScope(scope = "service:admin", description = "Service administration")
        })
    )
    @PUT
    @Path("/config")
    public Response updateConfiguration(ServiceConfig config) {
        // Requires service admin scope
    }
}

// Webhook endpoints
@Api(tags = "webhooks")
@Path("/webhooks")
public class WebhookController {
    
    @ApiOperation(
        value = "Payment webhook",
        authorizations = @Authorization(value = "webhook_key")
    )
    @POST
    @Path("/payment")
    public Response handlePaymentWebhook(PaymentEvent event) {
        // Webhook key in query parameter
    }
}

Best Practices

Security Definition Strategy

Use descriptive keys - Choose clear, meaningful names for security definition keys
Provide detailed descriptions - Help developers understand authentication requirements
Organize by purpose - Group related security schemes logically
Plan for multiple environments - Consider different auth URLs for dev/staging/prod

OAuth2 Implementation

Choose appropriate flows - Authorization Code for web apps, Client Credentials for services
Define granular scopes - Create specific permissions rather than broad access
Document scope hierarchies - Explain relationships between different permission levels
Include all required URLs - Ensure authorization and token URLs are correct for each flow

API Key Management

Use headers over query parameters - More secure transmission method
Choose descriptive parameter names - Clear field names improve developer experience
Support multiple key types - Different keys for different use cases (user vs service)
Document key formats - Specify expected key structure or encoding

Authorization Patterns

Principle of least privilege - Require only necessary scopes for each operation
Provide alternatives - Offer multiple authentication methods when appropriate
Document security implications - Explain what each authorization grants access to
Consider operation sensitivity - Apply stricter requirements for dangerous operations

Documentation Guidelines

Include realistic examples - Show actual usage patterns developers will encounter
Explain scope combinations - Document when multiple scopes are required
Provide troubleshooting info - Help developers diagnose authentication issues
Keep security descriptions current - Update documentation when auth schemes change

Install with Tessl CLI

npx tessl i tessl/maven-io-swagger--swagger-annotations

docs

tessl/maven-io-swagger--swagger-annotations

security.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Security Documentation

Capabilities

@Authorization Annotation

@AuthorizationScope Annotation

@SecurityDefinition Annotation

@OAuth2Definition Annotation

@ApiKeyAuthDefinition Annotation

@BasicAuthDefinition Annotation

@Scope Annotation (Enum)

Complex Security Scenarios

Multi-Tier Authentication

Microservices Security Architecture

Best Practices

Security Definition Strategy

OAuth2 Implementation

API Key Management

Authorization Patterns

Documentation Guidelines

security.mddocs/