0
# Enums Reference
1

2
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.
3

4
## Parameter Enums
5

6
### Parameter Location (ParameterIn)
7

8
Defines where a parameter is located in the HTTP request.
9

10
```java { .api }
11
/**
12
 * Specifies parameter location in HTTP request
13
 * Used by: @Parameter, @SecurityScheme
14
 */
15
enum ParameterIn {
16
    DEFAULT(""),        // Use annotation context default
17
    HEADER("header"),   // HTTP header parameter
18
    QUERY("query"),     // URL query string parameter
19
    PATH("path"),       // URL path segment parameter
20
    COOKIE("cookie")    // HTTP cookie parameter
21
}
22
```
23

24
**Usage Examples:**
25

26
```java
27
// Query parameter
28
@Parameter(
29
    name = "page",
30
    in = ParameterIn.QUERY,
31
    description = "Page number for pagination"
32
)
33

34
// Path parameter
35
@Parameter(
36
    name = "userId", 
37
    in = ParameterIn.PATH,
38
    description = "User identifier"
39
)
40

41
// Header parameter
42
@Parameter(
43
    name = "X-Client-Version",
44
    in = ParameterIn.HEADER,
45
    description = "Client application version"
46
)
47

48
// Cookie parameter
49
@Parameter(
50
    name = "sessionId",
51
    in = ParameterIn.COOKIE,
52
    description = "Session identifier"
53
)
54

55
// Default location (inferred from annotation context)
56
@Parameter(
57
    name = "filter",
58
    in = ParameterIn.DEFAULT,
59
    description = "Filter criteria"
60
)
61
```
62

63
### Parameter Style (ParameterStyle)
64

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

67
```java { .api }
68
/**
69
 * Specifies parameter serialization style
70
 * Used by: @Parameter, @Header, @Encoding
71
 */
72
enum ParameterStyle {
73
    DEFAULT(""),                    // Use location-specific default
74
    MATRIX("matrix"),               // ;color=blue,black,brown
75
    LABEL("label"),                 // .blue.black.brown  
76
    FORM("form"),                   // color=blue,black,brown
77
    SIMPLE("simple"),               // blue,black,brown
78
    SPACEDELIMITED("spaceDelimited"), // blue%20black%20brown
79
    PIPEDELIMITED("pipeDelimited"), // blue|black|brown
80
    DEEPOBJECT("deepObject")        // color[R]=100&color[G]=200
81
}
82
```
83

84
**Style Applications by Location:**
85

86
| Location | Default Style | Allowed Styles |
87
|----------|---------------|----------------|
88
| **query** | form | form, spaceDelimited, pipeDelimited, deepObject |
89
| **path** | simple | simple, label, matrix |
90
| **header** | simple | simple |
91
| **cookie** | form | form |
92
93
**Usage Examples:**
94

95
```java
96
// Form style for query parameters (default)
97
@Parameter(
98
    name = "tags",
99
    in = ParameterIn.QUERY,
100
    style = ParameterStyle.FORM,
101
    explode = Explode.TRUE,
102
    schema = @Schema(type = "array", items = @Schema(type = "string"))
103
)
104
// Result: ?tags=red&tags=blue&tags=green
105

106
// Space delimited style for query arrays
107
@Parameter(
108
    name = "categories",
109
    in = ParameterIn.QUERY,
110
    style = ParameterStyle.SPACEDELIMITED,
111
    explode = Explode.FALSE,
112
    schema = @Schema(type = "array")
113
)
114
// Result: ?categories=electronics%20books%20clothing
115

116
// Pipe delimited style
117
@Parameter(
118
    name = "statuses",
119
    in = ParameterIn.QUERY,
120
    style = ParameterStyle.PIPEDELIMITED,
121
    explode = Explode.FALSE
122
)
123
// Result: ?statuses=active|pending|completed
124

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

135
// Matrix style for path parameters
136
@Parameter(
137
    name = "coordinates",
138
    in = ParameterIn.PATH,
139
    style = ParameterStyle.MATRIX,
140
    explode = Explode.TRUE
141
)
142
// Result: /map;lat=50.4501;lon=30.5234
143

144
// Label style for path parameters
145
@Parameter(
146
    name = "point",
147
    in = ParameterIn.PATH,
148
    style = ParameterStyle.LABEL,
149
    explode = Explode.FALSE
150
)
151
// Result: /map/.50.4501.30.5234
152

153
// Simple style for headers (default)
154
@Parameter(
155
    name = "Accept-Language",
156
    in = ParameterIn.HEADER,
157
    style = ParameterStyle.SIMPLE,
158
    explode = Explode.FALSE
159
)
160
// Result: Accept-Language: en,fr,de
161
```
162

163
### Explode Behavior (Explode)
164

165
Controls how array and object parameters are expanded in serialization.
166

167
```java { .api }
168
/**
169
 * Controls parameter value explosion behavior
170
 * Used by: @Parameter, @Header, @Encoding
171
 */
172
enum Explode {
173
    DEFAULT,    // Use style-specific default behavior
174
    FALSE,      // Don't explode values (compact form)
175
    TRUE        // Explode values (expanded form)
176
}
177
```
178

179
**Default Explode Behavior by Style:**
180

181
| Style | Default Explode | Effect |
182
|-------|-----------------|--------|
183
| **form** | TRUE | `?tags=red&tags=blue` vs `?tags=red,blue` |
184
| **simple** | FALSE | `red,blue,green` |
185
| **matrix** | FALSE | `;tags=red,blue` vs `;tags=red;tags=blue` |
186
| **label** | FALSE | `.red.blue.green` |
187
| **spaceDelimited** | FALSE | `red%20blue%20green` |
188
| **pipeDelimited** | FALSE | `red|blue|green` |
189
| **deepObject** | TRUE | `obj[prop1]=val1&obj[prop2]=val2` |
190
191
**Usage Examples:**
192

193
```java
194
// Array parameter with explode=true (default for form style)
195
@Parameter(
196
    name = "tags",
197
    in = ParameterIn.QUERY,
198
    style = ParameterStyle.FORM,
199
    explode = Explode.TRUE,
200
    schema = @Schema(type = "array", items = @Schema(type = "string"))
201
)
202
// URL: ?tags=red&tags=blue&tags=green
203

204
// Array parameter with explode=false
205
@Parameter(
206
    name = "tags",
207
    in = ParameterIn.QUERY, 
208
    style = ParameterStyle.FORM,
209
    explode = Explode.FALSE,
210
    schema = @Schema(type = "array")
211
)
212
// URL: ?tags=red,blue,green
213

214
// Object parameter with explode=true
215
@Parameter(
216
    name = "user",
217
    in = ParameterIn.QUERY,
218
    style = ParameterStyle.DEEPOBJECT,
219
    explode = Explode.TRUE,
220
    schema = @Schema(implementation = UserFilter.class)
221
)
222
// URL: ?user[name]=john&user[age]=25&user[active]=true
223

224
// Object parameter with explode=false (not common for deepObject)
225
@Parameter(
226
    name = "coordinates",
227
    in = ParameterIn.PATH,
228
    style = ParameterStyle.SIMPLE,
229
    explode = Explode.FALSE,
230
    schema = @Schema(implementation = Point.class)
231
)
232
// Path: /location/50.4501,30.5234
233

234
// Header with multiple values, explode=false (default)
235
@Parameter(
236
    name = "Accept",
237
    in = ParameterIn.HEADER,
238
    style = ParameterStyle.SIMPLE,
239
    explode = Explode.FALSE,
240
    schema = @Schema(type = "array", items = @Schema(type = "string"))
241
)
242
// Header: Accept: application/json,application/xml,text/plain
243
```
244

245
## Security Enums
246

247
### Security Scheme Type (SecuritySchemeType)
248

249
Defines the type of security scheme used for API authentication.
250

251
```java { .api }
252
/**
253
 * Specifies security scheme type
254
 * Used by: @SecurityScheme
255
 */
256
enum SecuritySchemeType {
257
    DEFAULT(""),                    // No security scheme specified
258
    APIKEY("apiKey"),              // API key authentication
259
    HTTP("http"),                  // HTTP authentication (Basic, Bearer, etc.)
260
    OAUTH2("oauth2"),              // OAuth 2.0 authentication
261
    OPENIDCONNECT("openIdConnect"), // OpenID Connect authentication
262
    MUTUALTLS("mutualTLS")         // Mutual TLS authentication
263
}
264
```
265

266
**Usage Examples:**
267

268
```java
269
// API Key authentication
270
@SecurityScheme(
271
    name = "apiKeyAuth",
272
    type = SecuritySchemeType.APIKEY,
273
    in = SecuritySchemeIn.HEADER,
274
    paramName = "X-API-Key",
275
    description = "API key for authentication"
276
)
277

278
// HTTP Bearer token (JWT)
279
@SecurityScheme(
280
    name = "bearerAuth",
281
    type = SecuritySchemeType.HTTP,
282
    scheme = "bearer",
283
    bearerFormat = "JWT",
284
    description = "JWT Bearer token authentication"
285
)
286

287
// HTTP Basic authentication
288
@SecurityScheme(
289
    name = "basicAuth",
290
    type = SecuritySchemeType.HTTP,
291
    scheme = "basic",
292
    description = "HTTP Basic authentication"
293
)
294

295
// OAuth 2.0
296
@SecurityScheme(
297
    name = "oauth2",
298
    type = SecuritySchemeType.OAUTH2,
299
    description = "OAuth 2.0 authentication",
300
    flows = @OAuthFlows(
301
        authorizationCode = @OAuthFlow(
302
            authorizationUrl = "https://auth.example.com/oauth/authorize",
303
            tokenUrl = "https://auth.example.com/oauth/token"
304
        )
305
    )
306
)
307

308
// OpenID Connect
309
@SecurityScheme(
310
    name = "oidc",
311
    type = SecuritySchemeType.OPENIDCONNECT,
312
    openIdConnectUrl = "https://auth.example.com/.well-known/openid_configuration",
313
    description = "OpenID Connect authentication"
314
)
315

316
// Mutual TLS
317
@SecurityScheme(
318
    name = "mtls",
319
    type = SecuritySchemeType.MUTUALTLS,
320
    description = "Mutual TLS certificate authentication"
321
)
322

323
// No security (default)
324
@SecurityScheme(
325
    name = "noAuth",
326
    type = SecuritySchemeType.DEFAULT,
327
    description = "No authentication required"
328
)
329
```
330

331
### Security Scheme Location (SecuritySchemeIn)
332

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

335
```java { .api }
336
/**
337
 * Specifies API key parameter location
338
 * Used by: @SecurityScheme (only for APIKEY type)
339
 */
340
enum SecuritySchemeIn {
341
    DEFAULT(""),        // No location specified
342
    HEADER("header"),   // HTTP header
343
    QUERY("query"),     // URL query parameter
344
    COOKIE("cookie")    // HTTP cookie
345
}
346
```
347

348
**Usage Examples:**
349

350
```java
351
// API key in header (most common)
352
@SecurityScheme(
353
    name = "headerApiKey",
354
    type = SecuritySchemeType.APIKEY,
355
    in = SecuritySchemeIn.HEADER,
356
    paramName = "X-API-Key",
357
    description = "API key in header"
358
)
359
// Usage: X-API-Key: abc123def456
360

361
// API key in query parameter
362
@SecurityScheme(
363
    name = "queryApiKey",
364
    type = SecuritySchemeType.APIKEY,
365
    in = SecuritySchemeIn.QUERY,
366
    paramName = "api_key",
367
    description = "API key in query string"
368
)
369
// Usage: GET /api/users?api_key=abc123def456
370

371
// API key in cookie
372
@SecurityScheme(
373
    name = "cookieApiKey",
374
    type = SecuritySchemeType.APIKEY,
375
    in = SecuritySchemeIn.COOKIE,
376
    paramName = "apiKey",
377
    description = "API key in cookie"
378
)
379
// Usage: Cookie: apiKey=abc123def456
380

381
// Multiple API key schemes
382
@SecuritySchemes({
383
    @SecurityScheme(
384
        name = "adminApiKey",
385
        type = SecuritySchemeType.APIKEY,
386
        in = SecuritySchemeIn.HEADER,
387
        paramName = "X-Admin-Key",
388
        description = "Administrative API key"
389
    ),
390
    @SecurityScheme(
391
        name = "userApiKey", 
392
        type = SecuritySchemeType.APIKEY,
393
        in = SecuritySchemeIn.QUERY,
394
        paramName = "user_key",
395
        description = "User-specific API key"
396
    )
397
})
398
```
399

400
## Usage Patterns and Best Practices
401

402
### Parameter Style Selection Guide
403

404
```java
405
// Query Parameters
406
public class QueryParameterExamples {
407
    
408
    // Simple values - use default (form style)
409
    @Parameter(name = "search", in = ParameterIn.QUERY)
410
    
411
    // Arrays - choose based on preference
412
    @Parameter(
413
        name = "tags",
414
        in = ParameterIn.QUERY,
415
        style = ParameterStyle.FORM,        // tags=red&tags=blue (exploded)
416
        explode = Explode.TRUE
417
    )
418
    
419
    @Parameter(
420
        name = "categories",
421
        in = ParameterIn.QUERY,
422
        style = ParameterStyle.SPACEDELIMITED, // categories=books%20electronics
423
        explode = Explode.FALSE
424
    )
425
    
426
    // Complex objects
427
    @Parameter(
428
        name = "filter",
429
        in = ParameterIn.QUERY,
430
        style = ParameterStyle.DEEPOBJECT,  // filter[name]=john&filter[age]=25
431
        explode = Explode.TRUE
432
    )
433
}
434

435
// Path Parameters  
436
public class PathParameterExamples {
437
    
438
    // Simple values - use default (simple style)
439
    @Parameter(name = "id", in = ParameterIn.PATH)
440
    
441
    // Multiple values in path segment
442
    @Parameter(
443
        name = "coordinates",
444
        in = ParameterIn.PATH,
445
        style = ParameterStyle.MATRIX,      // ;lat=50.45;lon=30.52
446
        explode = Explode.TRUE
447
    )
448
    
449
    @Parameter(
450
        name = "point",
451
        in = ParameterIn.PATH,
452
        style = ParameterStyle.LABEL,       // .50.45.30.52
453
        explode = Explode.FALSE
454
    )
455
}
456

457
// Header Parameters
458
public class HeaderParameterExamples {
459
    
460
    // Headers always use simple style
461
    @Parameter(
462
        name = "X-Custom-Header",
463
        in = ParameterIn.HEADER,
464
        style = ParameterStyle.SIMPLE       // value1,value2,value3
465
    )
466
}
467
```
468

469
### Security Scheme Combinations
470

471
```java
472
// Multiple authentication options (user choice)
473
@SecurityRequirements({
474
    @SecurityRequirement(name = "bearerAuth"),     // Option 1: JWT
475
    @SecurityRequirement(name = "apiKeyAuth"),     // Option 2: API Key
476
    @SecurityRequirement(name = "basicAuth")       // Option 3: Basic Auth
477
})
478

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

483
// Conditional authentication by operation
484
@Path("/admin")
485
@SecurityRequirement(name = "adminAuth")    // Admin operations
486
public class AdminResource {
487
    
488
    @GET
489
    @Path("/public")
490
    @SecurityRequirement(name = "")         // Override: no auth needed
491
    public Response publicEndpoint() {}
492
    
493
    @DELETE  
494
    @Path("/critical")
495
    @SecurityRequirements({
496
        @SecurityRequirement(name = "adminAuth"),
497
        @SecurityRequirement(name = "mfaAuth")  // Additional MFA required
498
    })
499
    public Response criticalOperation() {}
500
}
501
```
502

503
### Complete Enum Usage Example
504

505
```java
506
@OpenAPIDefinition(
507
    info = @Info(title = "Complete Enum Demo API", version = "1.0"),
508
    security = @SecurityRequirement(name = "flexibleAuth")
509
)
510
@SecuritySchemes({
511
    @SecurityScheme(
512
        name = "flexibleAuth",
513
        type = SecuritySchemeType.HTTP,
514
        scheme = "bearer",
515
        bearerFormat = "JWT"
516
    ),
517
    @SecurityScheme(
518
        name = "apiKeyHeader",
519
        type = SecuritySchemeType.APIKEY,
520
        in = SecuritySchemeIn.HEADER,
521
        paramName = "X-API-Key"
522
    ),
523
    @SecurityScheme(
524
        name = "apiKeyQuery",
525
        type = SecuritySchemeType.APIKEY,
526
        in = SecuritySchemeIn.QUERY,
527
        paramName = "key"
528
    )
529
})
530
public class CompleteEnumDemoResource {
531
    
532
    @GET
533
    @Path("/search/{category}")
534
    @Operation(summary = "Search with comprehensive parameter styles")
535
    public Response search(
536
        // Path parameter with matrix style
537
        @Parameter(
538
            name = "category",
539
            in = ParameterIn.PATH,
540
            style = ParameterStyle.MATRIX,
541
            explode = Explode.TRUE,
542
            description = "Category with metadata"
543
        )
544
        @PathParam("category") String category,
545
        
546
        // Query array with space delimited style
547
        @Parameter(
548
            name = "tags",
549
            in = ParameterIn.QUERY,
550
            style = ParameterStyle.SPACEDELIMITED,
551
            explode = Explode.FALSE,
552
            schema = @Schema(type = "array", items = @Schema(type = "string"))
553
        )
554
        @QueryParam("tags") List<String> tags,
555
        
556
        // Complex filter object with deep object style
557
        @Parameter(
558
            name = "filter",
559
            in = ParameterIn.QUERY,
560
            style = ParameterStyle.DEEPOBJECT,
561
            explode = Explode.TRUE,
562
            schema = @Schema(implementation = SearchFilter.class)
563
        )
564
        @BeanParam SearchFilter filter,
565
        
566
        // Header parameter with simple style
567
        @Parameter(
568
            name = "Accept-Language",
569
            in = ParameterIn.HEADER,
570
            style = ParameterStyle.SIMPLE,
571
            explode = Explode.FALSE,
572
            schema = @Schema(type = "array", items = @Schema(type = "string"))
573
        )
574
        @HeaderParam("Accept-Language") List<String> languages,
575
        
576
        // Cookie parameter
577
        @Parameter(
578
            name = "preferences",
579
            in = ParameterIn.COOKIE,
580
            style = ParameterStyle.FORM,
581
            explode = Explode.TRUE
582
        ) 
583
        @CookieParam("preferences") String preferences
584
    ) {
585
        return Response.ok().build();
586
    }
587
}
588
```
589

590
## Enum Value Reference Table
591

592
### Quick Reference Summary
593

594
| Enum | Values | Common Usage |
595
|------|--------|--------------|
596
| **ParameterIn** | DEFAULT, HEADER, QUERY, PATH, COOKIE | Location of parameters in HTTP request |
597
| **ParameterStyle** | DEFAULT, FORM, SIMPLE, MATRIX, LABEL, SPACEDELIMITED, PIPEDELIMITED, DEEPOBJECT | How parameters are serialized |
598
| **Explode** | DEFAULT, TRUE, FALSE | Whether to expand array/object parameters |
599
| **SecuritySchemeType** | DEFAULT, APIKEY, HTTP, OAUTH2, OPENIDCONNECT, MUTUALTLS | Type of authentication scheme |
600
| **SecuritySchemeIn** | DEFAULT, HEADER, QUERY, COOKIE | Location of API key parameters |
601
602
### Migration and Compatibility Notes
603

604
When upgrading from older OpenAPI versions:
605

606
- **ParameterStyle.SPACEDELIMITED** and **ParameterStyle.PIPEDELIMITED** are OpenAPI 3.0+ features
607
- **ParameterStyle.DEEPOBJECT** is particularly useful for complex query objects
608
- **SecuritySchemeType.MUTUALTLS** is an OpenAPI 3.1 addition
609
- **SecuritySchemeType.OPENIDCONNECT** requires OpenAPI 3.0+
610

611
### Common Patterns by Framework
612

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

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

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