CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-io-swagger-core-v3--swagger-annotations-jakarta

Jakarta EE compatible OpenAPI 3.x annotations for defining REST API specifications

—

Pending
Overview
Eval results
Files

security.mddocs/

Security Configuration

Complete security scheme definitions supporting OAuth2 flows, API keys, HTTP authentication, OpenID Connect, and mutual TLS. This system provides comprehensive security documentation for REST APIs with flexible authentication and authorization patterns.

Capabilities

Security Scheme Definition

Defines security schemes in the OpenAPI components section with comprehensive authentication method support.

/**
 * Defines security schemes for API authentication
 * Applied to: TYPE, METHOD
 * Repeatable: Yes
 */
@SecurityScheme(
    name = "bearerAuth",                            // Security scheme name (required)
    type = SecuritySchemeType.HTTP,                 // Security scheme type (required)
    description = "JWT Bearer token authentication", // Scheme description
    
    // API Key configuration
    paramName = "X-API-Key",                        // Parameter name for API key
    in = SecuritySchemeIn.HEADER,                   // Location of API key
    
    // HTTP authentication
    scheme = "bearer",                              // HTTP auth scheme (basic, bearer, etc.)
    bearerFormat = "JWT",                           // Bearer token format
    
    // OAuth2 configuration  
    flows = @OAuthFlows(...),                       // OAuth2 flow definitions
    
    // OpenID Connect
    openIdConnectUrl = "https://auth.example.com/.well-known/openid_configuration",
    
    extensions = {@Extension(...)},                 // Custom extensions
    ref = "#/components/securitySchemes/BearerAuth" // Reference to component
)

Security Scheme Types:

enum SecuritySchemeType {
    DEFAULT(""),
    APIKEY("apiKey"),           // API key authentication
    HTTP("http"),               // HTTP authentication (basic, bearer, etc.)
    OAUTH2("oauth2"),           // OAuth2 authentication
    OPENIDCONNECT("openIdConnect"), // OpenID Connect
    MUTUALTLS("mutualTLS")      // Mutual TLS authentication
}

Security Scheme Locations:

enum SecuritySchemeIn {
    DEFAULT(""),
    HEADER("header"),           // Header parameter
    QUERY("query"),             // Query parameter  
    COOKIE("cookie")            // Cookie parameter
}

Usage Examples:

// JWT Bearer token
@SecurityScheme(
    name = "bearerAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "bearer", 
    bearerFormat = "JWT",
    description = "JWT Bearer token for API authentication"
)

// API Key in header
@SecurityScheme(
    name = "apiKeyAuth",
    type = SecuritySchemeType.APIKEY,
    in = SecuritySchemeIn.HEADER,
    paramName = "X-API-Key",
    description = "API key authentication via header"
)

// Basic HTTP authentication
@SecurityScheme(
    name = "basicAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "basic",
    description = "Basic HTTP authentication"
)

// OAuth2 with multiple flows
@SecurityScheme(
    name = "oauth2",
    type = SecuritySchemeType.OAUTH2,
    description = "OAuth2 authentication with multiple flows",
    flows = @OAuthFlows(
        authorizationCode = @OAuthFlow(
            authorizationUrl = "https://auth.example.com/oauth/authorize",
            tokenUrl = "https://auth.example.com/oauth/token",
            refreshUrl = "https://auth.example.com/oauth/refresh",
            scopes = {
                @OAuthScope(name = "read", description = "Read access to user data"),
                @OAuthScope(name = "write", description = "Write access to user data"),
                @OAuthScope(name = "admin", description = "Administrative access")
            }
        ),
        clientCredentials = @OAuthFlow(
            tokenUrl = "https://auth.example.com/oauth/token",
            scopes = {
                @OAuthScope(name = "api:read", description = "Read API access"),
                @OAuthScope(name = "api:write", description = "Write API access")
            }
        )
    )
)

// OpenID Connect
@SecurityScheme(
    name = "oidc",
    type = SecuritySchemeType.OPENIDCONNECT,
    openIdConnectUrl = "https://auth.example.com/.well-known/openid_configuration",
    description = "OpenID Connect authentication"
)

// Mutual TLS
@SecurityScheme(
    name = "mutualTLS",
    type = SecuritySchemeType.MUTUALTLS,
    description = "Mutual TLS certificate authentication"
)

Security Schemes Container

Container for multiple security scheme definitions.

/**
 * Container for multiple SecurityScheme annotations
 */
@SecuritySchemes({
    @SecurityScheme(name = "bearerAuth", type = SecuritySchemeType.HTTP, scheme = "bearer"),
    @SecurityScheme(name = "apiKey", type = SecuritySchemeType.APIKEY, in = SecuritySchemeIn.HEADER, paramName = "X-API-Key"),
    @SecurityScheme(name = "oauth2", type = SecuritySchemeType.OAUTH2, flows = @OAuthFlows(...))
})

Security Requirements

Defines which security schemes are required for operations or the entire API.

/**
 * Defines security requirements for operations
 * Applied to: METHOD, TYPE  
 * Repeatable: Yes
 */
@SecurityRequirement(
    name = "bearerAuth",                            // Security scheme name (required)
    scopes = {"read:users", "write:users"}         // Required scopes (for OAuth2/OIDC)
)

Usage Examples:

// Single security requirement
@GET
@Operation(summary = "Get user profile")
@SecurityRequirement(name = "bearerAuth")
public Response getUserProfile() {}

// Multiple security requirements (any one satisfies)
@GET
@Operation(summary = "Get public or authenticated content")
@SecurityRequirement(name = "bearerAuth")
@SecurityRequirement(name = "apiKey")
public Response getContent() {}

// OAuth2 with specific scopes
@POST
@Operation(summary = "Create user")
@SecurityRequirement(name = "oauth2", scopes = {"user:create", "admin"})
public Response createUser(@RequestBody CreateUserRequest request) {}

// Global security on class
@SecurityRequirement(name = "bearerAuth")
@Path("/admin")
public class AdminResource {
    // All operations inherit this security requirement
}

// Override security for specific operation
@GET
@Operation(summary = "Public health check")
@SecurityRequirement(name = "")  // Empty name = no security required
public Response healthCheck() {}

Security Requirements Container

Container for multiple security requirement definitions.

/**
 * Container for multiple SecurityRequirement annotations  
 */
@SecurityRequirements({
    @SecurityRequirement(name = "bearerAuth"),
    @SecurityRequirement(name = "apiKey"),
    @SecurityRequirement(name = "oauth2", scopes = {"read", "write"})
})

OAuth2 Flow Configuration

Comprehensive OAuth2 flow definitions supporting all standard OAuth2 flows.

/**
 * Defines OAuth2 flows configuration
 */
@OAuthFlows(
    implicit = @OAuthFlow(...),                     // Implicit flow
    password = @OAuthFlow(...),                     // Resource owner password flow
    clientCredentials = @OAuthFlow(...),            // Client credentials flow
    authorizationCode = @OAuthFlow(...),            // Authorization code flow
    extensions = {@Extension(...)}                  // Custom extensions
)

/**
 * Individual OAuth2 flow definition
 */
@OAuthFlow(
    authorizationUrl = "https://auth.example.com/oauth/authorize", // Authorization URL
    tokenUrl = "https://auth.example.com/oauth/token",            // Token URL (required)
    refreshUrl = "https://auth.example.com/oauth/refresh",        // Refresh URL
    scopes = {                                     // Available scopes
        @OAuthScope(name = "read", description = "Read access"),
        @OAuthScope(name = "write", description = "Write access")
    },
    extensions = {@Extension(...)}                  // Custom extensions
)

/**
 * OAuth2 scope definition
 */
@OAuthScope(
    name = "read:users",                           // Scope name (required)
    description = "Read access to user information" // Scope description
)

OAuth2 Flow Examples:

// Authorization Code Flow (most common for web apps)
@SecurityScheme(
    name = "oauth2AuthCode",
    type = SecuritySchemeType.OAUTH2,
    flows = @OAuthFlows(
        authorizationCode = @OAuthFlow(
            authorizationUrl = "https://auth.example.com/oauth/authorize",
            tokenUrl = "https://auth.example.com/oauth/token", 
            refreshUrl = "https://auth.example.com/oauth/refresh",
            scopes = {
                @OAuthScope(name = "profile", description = "Access to user profile"),
                @OAuthScope(name = "email", description = "Access to user email"),
                @OAuthScope(name = "admin", description = "Administrative access")
            }
        )
    )
)

// Client Credentials Flow (for service-to-service)
@SecurityScheme(
    name = "oauth2ClientCreds", 
    type = SecuritySchemeType.OAUTH2,
    flows = @OAuthFlows(
        clientCredentials = @OAuthFlow(
            tokenUrl = "https://auth.example.com/oauth/token",
            scopes = {
                @OAuthScope(name = "api:read", description = "Read API access"),
                @OAuthScope(name = "api:write", description = "Write API access"),
                @OAuthScope(name = "api:admin", description = "Admin API access")
            }
        )
    )
)

// Implicit Flow (for SPAs, deprecated but still supported)
@SecurityScheme(
    name = "oauth2Implicit",
    type = SecuritySchemeType.OAUTH2,
    flows = @OAuthFlows(
        implicit = @OAuthFlow(
            authorizationUrl = "https://auth.example.com/oauth/authorize",
            scopes = {
                @OAuthScope(name = "read", description = "Read access"),
                @OAuthScope(name = "write", description = "Write access")
            }
        )
    )
)

// Password Flow (for trusted first-party clients)
@SecurityScheme(
    name = "oauth2Password",
    type = SecuritySchemeType.OAUTH2, 
    flows = @OAuthFlows(
        password = @OAuthFlow(
            tokenUrl = "https://auth.example.com/oauth/token",
            refreshUrl = "https://auth.example.com/oauth/refresh",
            scopes = {
                @OAuthScope(name = "full_access", description = "Full user access")
            }
        )
    )
)

// Multiple flows in one scheme
@SecurityScheme(
    name = "oauth2Multi",
    type = SecuritySchemeType.OAUTH2,
    flows = @OAuthFlows(
        authorizationCode = @OAuthFlow(
            authorizationUrl = "https://auth.example.com/oauth/authorize", 
            tokenUrl = "https://auth.example.com/oauth/token",
            scopes = {@OAuthScope(name = "user", description = "User access")}
        ),
        clientCredentials = @OAuthFlow(
            tokenUrl = "https://auth.example.com/oauth/token",
            scopes = {@OAuthScope(name = "service", description = "Service access")}
        )
    )
)

Security Implementation Patterns

Global Security Configuration

@OpenAPIDefinition(
    info = @Info(title = "Secure API", version = "1.0"),
    security = {
        @SecurityRequirement(name = "bearerAuth"),
        @SecurityRequirement(name = "apiKey")  // Either bearer OR API key
    }
)
@SecuritySchemes({
    @SecurityScheme(
        name = "bearerAuth",
        type = SecuritySchemeType.HTTP,
        scheme = "bearer",
        bearerFormat = "JWT"
    ),
    @SecurityScheme(
        name = "apiKey", 
        type = SecuritySchemeType.APIKEY,
        in = SecuritySchemeIn.HEADER,
        paramName = "X-API-Key"
    )
})
public class SecureApplication {}

Resource-Level Security

@Path("/admin")
@SecurityRequirement(name = "oauth2", scopes = {"admin"})
public class AdminResource {
    
    @GET
    @Path("/users")
    @Operation(summary = "List all users - requires admin scope")
    public Response listUsers() {}
    
    @DELETE
    @Path("/users/{id}")
    @Operation(summary = "Delete user - requires admin scope") 
    @SecurityRequirement(name = "oauth2", scopes = {"admin", "user:delete"})
    public Response deleteUser(@PathParam("id") Long id) {}
}

Operation-Level Security Override

@Path("/api")
@SecurityRequirement(name = "bearerAuth")  // Default for all operations
public class ApiResource {
    
    @GET
    @Path("/public")
    @Operation(summary = "Public endpoint")
    @SecurityRequirement(name = "")  // Override: no security required
    public Response publicEndpoint() {}
    
    @GET
    @Path("/admin")
    @Operation(summary = "Admin endpoint")
    @SecurityRequirement(name = "oauth2", scopes = {"admin"})  // Override: OAuth2 required
    public Response adminEndpoint() {}
}

Multiple Security Options

@GET
@Operation(summary = "Flexible authentication endpoint")
@SecurityRequirements({
    @SecurityRequirement(name = "bearerAuth"),        // Option 1: JWT
    @SecurityRequirement(name = "apiKey"),            // Option 2: API Key  
    @SecurityRequirement(name = "basicAuth"),         // Option 3: Basic Auth
    @SecurityRequirement(name = "oauth2", scopes = {"read"}) // Option 4: OAuth2
})
public Response flexibleAuth() {}

Combined Security Requirements

@GET
@Operation(summary = "Requires both API key AND bearer token")
@SecurityRequirement(name = "apiKey")     // Separate requirements = both required
@SecurityRequirement(name = "bearerAuth") // Both must be satisfied
public Response combinedSecurity() {}

// Alternative syntax for combined requirements
@GET
@Operation(
    summary = "Multiple security schemes",
    security = {
        @SecurityRequirement(name = "apiKey"),
        @SecurityRequirement(name = "bearerAuth")
    }
)
public Response alternativeCombined() {}

Advanced Security Patterns

Custom Security Extensions

@SecurityScheme(
    name = "customAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "custom",
    extensions = {
        @Extension(
            name = "x-auth-type",
            properties = @ExtensionProperty(name = "type", value = "signature")
        ),
        @Extension(
            name = "x-signature-algorithm", 
            properties = @ExtensionProperty(name = "algorithm", value = "HMAC-SHA256")
        )
    }
)

Environment-Specific Security

@SecurityScheme(
    name = "envSpecificAuth",
    type = SecuritySchemeType.OAUTH2,
    flows = @OAuthFlows(
        authorizationCode = @OAuthFlow(
            authorizationUrl = "https://auth.{environment}.example.com/oauth/authorize",
            tokenUrl = "https://auth.{environment}.example.com/oauth/token"
        )
    ),
    extensions = {
        @Extension(
            name = "x-environment-urls",
            properties = {
                @ExtensionProperty(name = "dev", value = "https://auth.dev.example.com"),
                @ExtensionProperty(name = "staging", value = "https://auth.staging.example.com"),
                @ExtensionProperty(name = "prod", value = "https://auth.example.com")
            }
        )
    }
)

Conditional Security Based on Scopes

@GET
@Path("/users/{id}")
@Operation(summary = "Get user - different access levels")
@SecurityRequirements({
    @SecurityRequirement(name = "oauth2", scopes = {"user:read:own"}),     // Can read own data
    @SecurityRequirement(name = "oauth2", scopes = {"user:read:all"}),     // Can read any user data
    @SecurityRequirement(name = "oauth2", scopes = {"admin"})              // Admin access
})
public Response getUser(@PathParam("id") Long id) {}

Install with Tessl CLI

npx tessl i tessl/maven-io-swagger-core-v3--swagger-annotations-jakarta

docs

callbacks.md

core-annotations.md

enums.md

index.md

links.md

responses.md

schema-media.md

security.md

server-info.md

tile.json