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

Enums Reference

Name: tessl/maven-io-swagger-core-v3--swagger-annotations-jakarta
Author: tessl

Complete reference for all enumeration types used throughout the annotation system including parameter styles, security schemes, validation options, and OpenAPI specification features. These enums provide controlled vocabularies for various annotation attributes ensuring consistency and validation.

Parameter Enums

Parameter Location (ParameterIn)

Defines where a parameter is located in the HTTP request.

/**
 * Specifies parameter location in HTTP request
 * Used by: @Parameter, @SecurityScheme
 */
enum ParameterIn {
    DEFAULT(""),        // Use annotation context default
    HEADER("header"),   // HTTP header parameter
    QUERY("query"),     // URL query string parameter
    PATH("path"),       // URL path segment parameter
    COOKIE("cookie")    // HTTP cookie parameter
}

Usage Examples:

// Query parameter
@Parameter(
    name = "page",
    in = ParameterIn.QUERY,
    description = "Page number for pagination"
)

// Path parameter
@Parameter(
    name = "userId", 
    in = ParameterIn.PATH,
    description = "User identifier"
)

// Header parameter
@Parameter(
    name = "X-Client-Version",
    in = ParameterIn.HEADER,
    description = "Client application version"
)

// Cookie parameter
@Parameter(
    name = "sessionId",
    in = ParameterIn.COOKIE,
    description = "Session identifier"
)

// Default location (inferred from annotation context)
@Parameter(
    name = "filter",
    in = ParameterIn.DEFAULT,
    description = "Filter criteria"
)

Parameter Style (ParameterStyle)

Defines how parameter values are serialized, especially for arrays and objects.

/**
 * Specifies parameter serialization style
 * Used by: @Parameter, @Header, @Encoding
 */
enum ParameterStyle {
    DEFAULT(""),                    // Use location-specific default
    MATRIX("matrix"),               // ;color=blue,black,brown
    LABEL("label"),                 // .blue.black.brown  
    FORM("form"),                   // color=blue,black,brown
    SIMPLE("simple"),               // blue,black,brown
    SPACEDELIMITED("spaceDelimited"), // blue%20black%20brown
    PIPEDELIMITED("pipeDelimited"), // blue|black|brown
    DEEPOBJECT("deepObject")        // color[R]=100&color[G]=200
}

Style Applications by Location:

Location	Default Style	Allowed Styles
query	form	form, spaceDelimited, pipeDelimited, deepObject
path	simple	simple, label, matrix
header	simple	simple
cookie	form	form

Usage Examples:

// Form style for query parameters (default)
@Parameter(
    name = "tags",
    in = ParameterIn.QUERY,
    style = ParameterStyle.FORM,
    explode = Explode.TRUE,
    schema = @Schema(type = "array", items = @Schema(type = "string"))
)
// Result: ?tags=red&tags=blue&tags=green

// Space delimited style for query arrays
@Parameter(
    name = "categories",
    in = ParameterIn.QUERY,
    style = ParameterStyle.SPACEDELIMITED,
    explode = Explode.FALSE,
    schema = @Schema(type = "array")
)
// Result: ?categories=electronics%20books%20clothing

// Pipe delimited style
@Parameter(
    name = "statuses",
    in = ParameterIn.QUERY,
    style = ParameterStyle.PIPEDELIMITED,
    explode = Explode.FALSE
)
// Result: ?statuses=active|pending|completed

// Deep object style for complex objects
@Parameter(
    name = "filter",
    in = ParameterIn.QUERY,
    style = ParameterStyle.DEEPOBJECT,
    explode = Explode.TRUE,
    schema = @Schema(implementation = FilterCriteria.class)
)
// Result: ?filter[name]=john&filter[age][min]=18&filter[age][max]=65

// Matrix style for path parameters
@Parameter(
    name = "coordinates",
    in = ParameterIn.PATH,
    style = ParameterStyle.MATRIX,
    explode = Explode.TRUE
)
// Result: /map;lat=50.4501;lon=30.5234

// Label style for path parameters
@Parameter(
    name = "point",
    in = ParameterIn.PATH,
    style = ParameterStyle.LABEL,
    explode = Explode.FALSE
)
// Result: /map/.50.4501.30.5234

// Simple style for headers (default)
@Parameter(
    name = "Accept-Language",
    in = ParameterIn.HEADER,
    style = ParameterStyle.SIMPLE,
    explode = Explode.FALSE
)
// Result: Accept-Language: en,fr,de

Explode Behavior (Explode)

Controls how array and object parameters are expanded in serialization.

/**
 * Controls parameter value explosion behavior
 * Used by: @Parameter, @Header, @Encoding
 */
enum Explode {
    DEFAULT,    // Use style-specific default behavior
    FALSE,      // Don't explode values (compact form)
    TRUE        // Explode values (expanded form)
}

Default Explode Behavior by Style:

Style	Default Explode	Effect
form	TRUE	`?tags=red&tags=blue` vs `?tags=red,blue`
simple	FALSE	`red,blue,green`
matrix	FALSE	`;tags=red,blue` vs `;tags=red;tags=blue`
label	FALSE	`.red.blue.green`
spaceDelimited	FALSE	`red%20blue%20green`
pipeDelimited	FALSE	`red
deepObject	TRUE	`obj[prop1]=val1&obj[prop2]=val2`

Usage Examples:

// Array parameter with explode=true (default for form style)
@Parameter(
    name = "tags",
    in = ParameterIn.QUERY,
    style = ParameterStyle.FORM,
    explode = Explode.TRUE,
    schema = @Schema(type = "array", items = @Schema(type = "string"))
)
// URL: ?tags=red&tags=blue&tags=green

// Array parameter with explode=false
@Parameter(
    name = "tags",
    in = ParameterIn.QUERY, 
    style = ParameterStyle.FORM,
    explode = Explode.FALSE,
    schema = @Schema(type = "array")
)
// URL: ?tags=red,blue,green

// Object parameter with explode=true
@Parameter(
    name = "user",
    in = ParameterIn.QUERY,
    style = ParameterStyle.DEEPOBJECT,
    explode = Explode.TRUE,
    schema = @Schema(implementation = UserFilter.class)
)
// URL: ?user[name]=john&user[age]=25&user[active]=true

// Object parameter with explode=false (not common for deepObject)
@Parameter(
    name = "coordinates",
    in = ParameterIn.PATH,
    style = ParameterStyle.SIMPLE,
    explode = Explode.FALSE,
    schema = @Schema(implementation = Point.class)
)
// Path: /location/50.4501,30.5234

// Header with multiple values, explode=false (default)
@Parameter(
    name = "Accept",
    in = ParameterIn.HEADER,
    style = ParameterStyle.SIMPLE,
    explode = Explode.FALSE,
    schema = @Schema(type = "array", items = @Schema(type = "string"))
)
// Header: Accept: application/json,application/xml,text/plain

Security Enums

Security Scheme Type (SecuritySchemeType)

Defines the type of security scheme used for API authentication.

/**
 * Specifies security scheme type
 * Used by: @SecurityScheme
 */
enum SecuritySchemeType {
    DEFAULT(""),                    // No security scheme specified
    APIKEY("apiKey"),              // API key authentication
    HTTP("http"),                  // HTTP authentication (Basic, Bearer, etc.)
    OAUTH2("oauth2"),              // OAuth 2.0 authentication
    OPENIDCONNECT("openIdConnect"), // OpenID Connect authentication
    MUTUALTLS("mutualTLS")         // Mutual TLS authentication
}

Usage Examples:

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

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

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

// OAuth 2.0
@SecurityScheme(
    name = "oauth2",
    type = SecuritySchemeType.OAUTH2,
    description = "OAuth 2.0 authentication",
    flows = @OAuthFlows(
        authorizationCode = @OAuthFlow(
            authorizationUrl = "https://auth.example.com/oauth/authorize",
            tokenUrl = "https://auth.example.com/oauth/token"
        )
    )
)

// 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 = "mtls",
    type = SecuritySchemeType.MUTUALTLS,
    description = "Mutual TLS certificate authentication"
)

// No security (default)
@SecurityScheme(
    name = "noAuth",
    type = SecuritySchemeType.DEFAULT,
    description = "No authentication required"
)

Security Scheme Location (SecuritySchemeIn)

Defines where API key security parameters are located in the HTTP request.

/**
 * Specifies API key parameter location
 * Used by: @SecurityScheme (only for APIKEY type)
 */
enum SecuritySchemeIn {
    DEFAULT(""),        // No location specified
    HEADER("header"),   // HTTP header
    QUERY("query"),     // URL query parameter
    COOKIE("cookie")    // HTTP cookie
}

Usage Examples:

// API key in header (most common)
@SecurityScheme(
    name = "headerApiKey",
    type = SecuritySchemeType.APIKEY,
    in = SecuritySchemeIn.HEADER,
    paramName = "X-API-Key",
    description = "API key in header"
)
// Usage: X-API-Key: abc123def456

// API key in query parameter
@SecurityScheme(
    name = "queryApiKey",
    type = SecuritySchemeType.APIKEY,
    in = SecuritySchemeIn.QUERY,
    paramName = "api_key",
    description = "API key in query string"
)
// Usage: GET /api/users?api_key=abc123def456

// API key in cookie
@SecurityScheme(
    name = "cookieApiKey",
    type = SecuritySchemeType.APIKEY,
    in = SecuritySchemeIn.COOKIE,
    paramName = "apiKey",
    description = "API key in cookie"
)
// Usage: Cookie: apiKey=abc123def456

// Multiple API key schemes
@SecuritySchemes({
    @SecurityScheme(
        name = "adminApiKey",
        type = SecuritySchemeType.APIKEY,
        in = SecuritySchemeIn.HEADER,
        paramName = "X-Admin-Key",
        description = "Administrative API key"
    ),
    @SecurityScheme(
        name = "userApiKey", 
        type = SecuritySchemeType.APIKEY,
        in = SecuritySchemeIn.QUERY,
        paramName = "user_key",
        description = "User-specific API key"
    )
})

Usage Patterns and Best Practices

Parameter Style Selection Guide

// Query Parameters
public class QueryParameterExamples {
    
    // Simple values - use default (form style)
    @Parameter(name = "search", in = ParameterIn.QUERY)
    
    // Arrays - choose based on preference
    @Parameter(
        name = "tags",
        in = ParameterIn.QUERY,
        style = ParameterStyle.FORM,        // tags=red&tags=blue (exploded)
        explode = Explode.TRUE
    )
    
    @Parameter(
        name = "categories",
        in = ParameterIn.QUERY,
        style = ParameterStyle.SPACEDELIMITED, // categories=books%20electronics
        explode = Explode.FALSE
    )
    
    // Complex objects
    @Parameter(
        name = "filter",
        in = ParameterIn.QUERY,
        style = ParameterStyle.DEEPOBJECT,  // filter[name]=john&filter[age]=25
        explode = Explode.TRUE
    )
}

// Path Parameters  
public class PathParameterExamples {
    
    // Simple values - use default (simple style)
    @Parameter(name = "id", in = ParameterIn.PATH)
    
    // Multiple values in path segment
    @Parameter(
        name = "coordinates",
        in = ParameterIn.PATH,
        style = ParameterStyle.MATRIX,      // ;lat=50.45;lon=30.52
        explode = Explode.TRUE
    )
    
    @Parameter(
        name = "point",
        in = ParameterIn.PATH,
        style = ParameterStyle.LABEL,       // .50.45.30.52
        explode = Explode.FALSE
    )
}

// Header Parameters
public class HeaderParameterExamples {
    
    // Headers always use simple style
    @Parameter(
        name = "X-Custom-Header",
        in = ParameterIn.HEADER,
        style = ParameterStyle.SIMPLE       // value1,value2,value3
    )
}

Security Scheme Combinations

// Multiple authentication options (user choice)
@SecurityRequirements({
    @SecurityRequirement(name = "bearerAuth"),     // Option 1: JWT
    @SecurityRequirement(name = "apiKeyAuth"),     // Option 2: API Key
    @SecurityRequirement(name = "basicAuth")       // Option 3: Basic Auth
})

// Combined authentication (both required)  
@SecurityRequirement(name = "apiKey")       // Both API key AND
@SecurityRequirement(name = "bearerAuth")   // Bearer token required

// Conditional authentication by operation
@Path("/admin")
@SecurityRequirement(name = "adminAuth")    // Admin operations
public class AdminResource {
    
    @GET
    @Path("/public")
    @SecurityRequirement(name = "")         // Override: no auth needed
    public Response publicEndpoint() {}
    
    @DELETE  
    @Path("/critical")
    @SecurityRequirements({
        @SecurityRequirement(name = "adminAuth"),
        @SecurityRequirement(name = "mfaAuth")  // Additional MFA required
    })
    public Response criticalOperation() {}
}

Complete Enum Usage Example

@OpenAPIDefinition(
    info = @Info(title = "Complete Enum Demo API", version = "1.0"),
    security = @SecurityRequirement(name = "flexibleAuth")
)
@SecuritySchemes({
    @SecurityScheme(
        name = "flexibleAuth",
        type = SecuritySchemeType.HTTP,
        scheme = "bearer",
        bearerFormat = "JWT"
    ),
    @SecurityScheme(
        name = "apiKeyHeader",
        type = SecuritySchemeType.APIKEY,
        in = SecuritySchemeIn.HEADER,
        paramName = "X-API-Key"
    ),
    @SecurityScheme(
        name = "apiKeyQuery",
        type = SecuritySchemeType.APIKEY,
        in = SecuritySchemeIn.QUERY,
        paramName = "key"
    )
})
public class CompleteEnumDemoResource {
    
    @GET
    @Path("/search/{category}")
    @Operation(summary = "Search with comprehensive parameter styles")
    public Response search(
        // Path parameter with matrix style
        @Parameter(
            name = "category",
            in = ParameterIn.PATH,
            style = ParameterStyle.MATRIX,
            explode = Explode.TRUE,
            description = "Category with metadata"
        )
        @PathParam("category") String category,
        
        // Query array with space delimited style
        @Parameter(
            name = "tags",
            in = ParameterIn.QUERY,
            style = ParameterStyle.SPACEDELIMITED,
            explode = Explode.FALSE,
            schema = @Schema(type = "array", items = @Schema(type = "string"))
        )
        @QueryParam("tags") List<String> tags,
        
        // Complex filter object with deep object style
        @Parameter(
            name = "filter",
            in = ParameterIn.QUERY,
            style = ParameterStyle.DEEPOBJECT,
            explode = Explode.TRUE,
            schema = @Schema(implementation = SearchFilter.class)
        )
        @BeanParam SearchFilter filter,
        
        // Header parameter with simple style
        @Parameter(
            name = "Accept-Language",
            in = ParameterIn.HEADER,
            style = ParameterStyle.SIMPLE,
            explode = Explode.FALSE,
            schema = @Schema(type = "array", items = @Schema(type = "string"))
        )
        @HeaderParam("Accept-Language") List<String> languages,
        
        // Cookie parameter
        @Parameter(
            name = "preferences",
            in = ParameterIn.COOKIE,
            style = ParameterStyle.FORM,
            explode = Explode.TRUE
        ) 
        @CookieParam("preferences") String preferences
    ) {
        return Response.ok().build();
    }
}

Enum Value Reference Table

Quick Reference Summary

Enum	Values	Common Usage
ParameterIn	DEFAULT, HEADER, QUERY, PATH, COOKIE	Location of parameters in HTTP request
ParameterStyle	DEFAULT, FORM, SIMPLE, MATRIX, LABEL, SPACEDELIMITED, PIPEDELIMITED, DEEPOBJECT	How parameters are serialized
Explode	DEFAULT, TRUE, FALSE	Whether to expand array/object parameters
SecuritySchemeType	DEFAULT, APIKEY, HTTP, OAUTH2, OPENIDCONNECT, MUTUALTLS	Type of authentication scheme
SecuritySchemeIn	DEFAULT, HEADER, QUERY, COOKIE	Location of API key parameters

Migration and Compatibility Notes

When upgrading from older OpenAPI versions:

ParameterStyle.SPACEDELIMITED and ParameterStyle.PIPEDELIMITED are OpenAPI 3.0+ features
ParameterStyle.DEEPOBJECT is particularly useful for complex query objects
SecuritySchemeType.MUTUALTLS is an OpenAPI 3.1 addition
SecuritySchemeType.OPENIDCONNECT requires OpenAPI 3.0+

Common Patterns by Framework

// JAX-RS with Jersey
@QueryParam("tags") @Parameter(style = ParameterStyle.FORM, explode = Explode.TRUE) List<String> tags

// Spring Boot
@RequestParam("tags") @Parameter(style = ParameterStyle.FORM, explode = Explode.TRUE) List<String> tags

// Quarkus
@QueryParam("tags") @Parameter(style = ParameterStyle.FORM, explode = Explode.TRUE) List<String> tags

Install with Tessl CLI

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

docs

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

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

Enums Reference

Parameter Enums

Parameter Location (ParameterIn)

Parameter Style (ParameterStyle)

Explode Behavior (Explode)

Security Enums

Security Scheme Type (SecuritySchemeType)

Security Scheme Location (SecuritySchemeIn)

Usage Patterns and Best Practices

Parameter Style Selection Guide

Security Scheme Combinations

Complete Enum Usage Example

Enum Value Reference Table

Quick Reference Summary

Migration and Compatibility Notes

Common Patterns by Framework

enums.mddocs/