0
# Core Annotations
1

2
Essential annotations for documenting REST operations, parameters, and API structure. These annotations form the foundation of OpenAPI documentation and are used to define operations, parameters, and overall API configuration.
3

4
## Capabilities
5

6
### Operation Definition
7

8
Defines a resource method as an OpenAPI Operation with comprehensive metadata and configuration options.
9

10
```java { .api }
11
/**
12
 * Defines a resource method as an OpenAPI Operation
13
 * Applied to: METHOD, ANNOTATION_TYPE
14
 */
15
@Operation(
16
    method = "GET",                                    // HTTP method
17
    tags = {"users", "management"},                    // Logical grouping tags
18
    summary = "Get user by ID",                        // Brief description (≤120 chars)
19
    description = "Retrieves user account details",   // Verbose description
20
    operationId = "getUserById",                       // Unique operation identifier
21
    deprecated = false,                                // Deprecation status
22
    hidden = false,                                    // Hide from documentation
23
    ignoreJsonView = false,                           // Ignore JsonView annotations
24
    parameters = {@Parameter(...)},                    // Operation parameters
25
    responses = {@ApiResponse(...)},                   // Possible responses
26
    requestBody = @RequestBody(...),                   // Associated request body
27
    security = {@SecurityRequirement(...)},           // Security requirements
28
    servers = {@Server(...)},                         // Alternative servers
29
    externalDocs = @ExternalDocumentation(...),       // External documentation
30
    extensions = {@Extension(...)}                     // Custom extensions
31
)
32
```
33

34
**Usage Example:**
35

36
```java
37
@GET
38
@Path("/{id}")
39
@Operation(
40
    summary = "Get user by ID",
41
    description = "Retrieves a user account by their unique identifier",
42
    operationId = "getUserById",
43
    tags = {"users"}
44
)
45
@ApiResponse(responseCode = "200", description = "User found")
46
@ApiResponse(responseCode = "404", description = "User not found")
47
public Response getUserById(@PathParam("id") Long id) {
48
    // Implementation
49
}
50
```
51

52
### Parameter Definition
53

54
Defines method parameters as operation parameters with location, validation, and schema information.
55

56
```java { .api }
57
/**
58
 * Defines operation parameters with comprehensive configuration
59
 * Applied to: METHOD, FIELD, PARAMETER, ANNOTATION_TYPE
60
 * Repeatable: Yes
61
 */
62
@Parameter(
63
    name = "userId",                                  // Parameter name (required for non-path params)
64
    in = ParameterIn.PATH,                           // Parameter location
65
    description = "Unique user identifier",          // Parameter description
66
    required = true,                                 // Whether parameter is mandatory
67
    deprecated = false,                              // Deprecation status
68
    allowEmptyValue = false,                         // Allow empty values
69
    hidden = false,                                  // Hide from documentation
70
    style = ParameterStyle.SIMPLE,                   // Serialization style
71
    explode = Explode.DEFAULT,                       // Explode array/object parameters
72
    allowReserved = false,                           // Allow reserved characters
73
    schema = @Schema(type = "integer", format = "int64"), // Parameter schema
74
    array = @ArraySchema(...),                       // Array schema alternative
75
    content = {@Content(...)},                       // Complex parameter content
76
    example = "12345",                               // Example value
77
    examples = {@ExampleObject(...)},                // Multiple examples
78
    extensions = {@Extension(...)},                   // Custom extensions
79
    ref = "#/components/parameters/UserIdParam",     // Reference to component
80
    validationGroups = {}                            // Validation groups
81
)
82
```
83

84
**Parameter Location Types:**
85

86
```java { .api }
87
enum ParameterIn {
88
    DEFAULT(""),
89
    HEADER("header"),
90
    QUERY("query"), 
91
    PATH("path"),
92
    COOKIE("cookie")
93
}
94
```
95

96
**Parameter Styles:**
97

98
```java { .api }
99
enum ParameterStyle {
100
    DEFAULT(""),
101
    MATRIX("matrix"),           // ;color=blue,black,brown
102
    LABEL("label"),             // .blue.black.brown
103
    FORM("form"),               // color=blue,black,brown
104
    SPACEDELIMITED("spaceDelimited"), // blue%20black%20brown
105
    PIPEDELIMITED("pipeDelimited"),   // blue|black|brown
106
    DEEPOBJECT("deepObject"),   // color[R]=100&color[G]=200
107
    SIMPLE("simple")            // blue,black,brown
108
}
109
```
110

111
**Usage Examples:**
112

113
```java
114
// Path parameter
115
@GET
116
@Path("/{userId}")
117
public Response getUser(
118
    @Parameter(description = "User ID", required = true)
119
    @PathParam("userId") Long userId
120
) {}
121

122
// Query parameters with validation
123
@GET
124
public Response getUsers(
125
    @Parameter(
126
        name = "page",
127
        description = "Page number for pagination",
128
        schema = @Schema(type = "integer", minimum = "1", defaultValue = "1")
129
    )
130
    @QueryParam("page") Integer page,
131
    
132
    @Parameter(
133
        name = "size", 
134
        description = "Number of items per page",
135
        schema = @Schema(type = "integer", minimum = "1", maximum = "100", defaultValue = "20")
136
    )
137
    @QueryParam("size") Integer size
138
) {}
139

140
// Header parameter
141
@GET
142
public Response getData(
143
    @Parameter(
144
        name = "X-Client-Version",
145
        in = ParameterIn.HEADER, 
146
        description = "Client version",
147
        schema = @Schema(type = "string", pattern = "^\\d+\\.\\d+\\.\\d+$")
148
    )
149
    @HeaderParam("X-Client-Version") String clientVersion
150
) {}
151
```
152

153
### Parameters Container
154

155
Container annotation for multiple Parameter annotations on the same element.
156

157
```java { .api }
158
/**
159
 * Container for repeatable Parameter annotations
160
 */
161
@Parameters({
162
    @Parameter(name = "userId", in = ParameterIn.PATH, required = true),
163
    @Parameter(name = "includeDetails", in = ParameterIn.QUERY, required = false)
164
})
165
```
166

167
### Validated Parameter
168

169
Extends parameter definition with validation group support for conditional validation scenarios.
170

171
```java { .api }
172
/**
173
 * Parameter with validation group support
174
 * Applied to: PARAMETER, FIELD, METHOD
175
 */
176
@ValidatedParameter(
177
    name = "email",                                 // Parameter name
178
    in = ParameterIn.QUERY,                        // Parameter location
179
    description = "Email address for validation",  // Parameter description
180
    required = true,                               // Required flag
181
    schema = @Schema(type = "string", format = "email"), // Parameter schema
182
    validationGroups = {Create.class, Update.class}     // Validation groups
183
)
184
```
185

186
**Usage Examples:**
187

188
```java
189
// Parameter with create-only validation
190
@POST
191
@Path("/users")
192
public Response createUser(
193
    @ValidatedParameter(
194
        name = "email",
195
        description = "User email address",
196
        required = true,
197
        schema = @Schema(type = "string", format = "email"),
198
        validationGroups = {CreateUser.class}
199
    )
200
    @QueryParam("email") String email
201
) {}
202

203
// Parameter with different validation for different operations
204
@PUT
205
@Path("/users/{id}")
206
public Response updateUser(
207
    @PathParam("id") Long id,
208
    @ValidatedParameter(
209
        name = "email",
210
        description = "Updated email address",
211
        required = false,  // Optional for updates
212
        schema = @Schema(type = "string", format = "email"),
213
        validationGroups = {UpdateUser.class}
214
    )
215
    @QueryParam("email") String email
216
) {}
217

218
// Multiple validation groups
219
@Parameter(
220
    name = "password",
221
    description = "User password",
222
    required = true,
223
    schema = @Schema(type = "string", minLength = 8),
224
    validationGroups = {CreateUser.class, ChangePassword.class}
225
)
226
```
227

228
### OpenAPI Definition
229

230
Populates the root OpenAPI Object with API metadata, security, servers, and global configuration.
231

232
```java { .api }
233
/**
234
 * Defines global OpenAPI configuration
235
 * Applied to: TYPE
236
 */
237
@OpenAPIDefinition(
238
    info = @Info(                                    // API metadata (required)
239
        title = "User Management API",
240
        version = "2.1.0",
241
        description = "Complete user management system"
242
    ),
243
    tags = {                                         // Global tags with metadata
244
        @Tag(name = "users", description = "User operations"),
245
        @Tag(name = "admin", description = "Administrative operations")
246
    },
247
    servers = {                                      // Server configurations
248
        @Server(url = "https://api.example.com", description = "Production"),
249
        @Server(url = "https://staging-api.example.com", description = "Staging")
250
    },
251
    security = {                                     // Global security requirements
252
        @SecurityRequirement(name = "bearerAuth", scopes = {"read", "write"})
253
    },
254
    externalDocs = @ExternalDocumentation(           // Additional documentation
255
        description = "API Documentation",
256
        url = "https://docs.example.com"
257
    ),
258
    extensions = {@Extension(...)}                   // Custom extensions
259
)
260
```
261

262
**Usage Example:**
263

264
```java
265
@OpenAPIDefinition(
266
    info = @Info(
267
        title = "E-commerce API",
268
        version = "3.0.0",
269
        description = "RESTful API for e-commerce operations",
270
        contact = @Contact(
271
            name = "API Support",
272
            email = "support@example.com",
273
            url = "https://example.com/support"
274
        ),
275
        license = @License(
276
            name = "Apache 2.0",
277
            url = "https://www.apache.org/licenses/LICENSE-2.0.html"
278
        )
279
    ),
280
    servers = {
281
        @Server(
282
            url = "https://api.{environment}.example.com",
283
            description = "Main API server",
284
            variables = @ServerVariable(
285
                name = "environment",
286
                defaultValue = "prod",
287
                allowableValues = {"dev", "staging", "prod"},
288
                description = "Deployment environment"
289
            )
290
        )
291
    },
292
    security = {
293
        @SecurityRequirement(name = "oauth2", scopes = {"read", "write"}),
294
        @SecurityRequirement(name = "apiKey")
295
    }
296
)
297
@ApplicationPath("/api/v3")
298
public class ECommerceApplication extends Application {}
299
```
300

301
### Hidden Annotation
302

303
Marks elements as hidden from OpenAPI documentation generation.
304

305
```java { .api }
306
/**
307
 * Marks elements as hidden from OpenAPI documentation
308
 * Applied to: METHOD, TYPE, FIELD, ANNOTATION_TYPE
309
 */
310
@Hidden
311
```
312

313
**Usage Examples:**
314

315
```java
316
// Hide entire resource class
317
@Hidden
318
@Path("/internal")
319
public class InternalResource {}
320

321
// Hide specific operation
322
@GET
323
@Hidden
324
@Operation(summary = "Internal operation")
325
public Response internalOperation() {}
326

327
// Hide parameter
328
public Response getUser(
329
    @Hidden @QueryParam("debug") Boolean debug,
330
    @PathParam("id") Long id
331
) {}
332
```
333

334
### External Documentation
335

336
Adds references to external documentation for various OpenAPI elements.
337

338
```java { .api }
339
/**
340
 * Links to external documentation
341
 * Applied to: various annotation elements
342
 */
343
@ExternalDocumentation(
344
    description = "User guide documentation",        // Short description
345
    url = "https://docs.example.com/users",         // Documentation URL (required)
346
    extensions = {@Extension(...)}                   // Custom extensions
347
)
348
```
349

350
**Usage Examples:**
351

352
```java
353
// On operation
354
@Operation(
355
    summary = "Complex operation",
356
    externalDocs = @ExternalDocumentation(
357
        description = "Detailed usage guide",
358
        url = "https://docs.example.com/complex-operations"
359
    )
360
)
361

362
// On tag
363
@Tag(
364
    name = "advanced",
365
    description = "Advanced operations",
366
    externalDocs = @ExternalDocumentation(
367
        description = "Advanced features guide", 
368
        url = "https://docs.example.com/advanced"
369
    )
370
)
371
```
372

373
### Extensions System
374

375
Custom extensions for adding vendor-specific or additional metadata to OpenAPI elements.
376

377
```java { .api }
378
/**
379
 * Custom OpenAPI extension
380
 * Repeatable: Yes
381
 */
382
@Extension(
383
    name = "x-custom-property",                      // Extension name (prefixed with x-)
384
    properties = {                                   // Extension properties
385
        @ExtensionProperty(name = "enabled", value = "true"),
386
        @ExtensionProperty(name = "level", value = "2", parseValue = true)
387
    }
388
)
389

390
/**
391
 * Extension property within an extension
392
 */
393
@ExtensionProperty(
394
    name = "propertyName",                           // Property name
395
    value = "propertyValue",                         // Property value
396
    parseValue = false                               // Parse as JSON/YAML
397
)
398
```
399

400
**Usage Examples:**
401

402
```java
403
@Operation(
404
    summary = "Custom operation",
405
    extensions = {
406
        @Extension(
407
            name = "x-rate-limit",
408
            properties = {
409
                @ExtensionProperty(name = "requests", value = "100"),
410
                @ExtensionProperty(name = "window", value = "3600")
411
            }
412
        ),
413
        @Extension(
414
            name = "x-feature-flags", 
415
            properties = @ExtensionProperty(
416
                name = "config",
417
                value = "{\"beta\": true, \"experimental\": false}",
418
                parseValue = true
419
            )
420
        )
421
    }
422
)
423
```
424

425
### Webhook Support (OpenAPI 3.1)
426

427
Defines webhook operations for event-driven API interactions.
428

429
```java { .api }
430
/**
431
 * Defines webhook operation (OpenAPI 3.1)
432
 * Repeatable: Yes
433
 */
434
@Webhook(
435
    name = "userCreated",                            // Webhook name
436
    operation = @Operation(                          // Webhook operation definition
437
        summary = "User created notification",
438
        requestBody = @RequestBody(
439
            content = @Content(schema = @Schema(implementation = UserEvent.class))
440
        )
441
    )
442
)
443

444
/**
445
 * Container for multiple webhooks
446
 */
447
@Webhooks({
448
    @Webhook(name = "userCreated", operation = @Operation(...)),
449
    @Webhook(name = "userUpdated", operation = @Operation(...))
450
})
451
```
452

453
### String to Class Mapping
454

455
Maps string identifiers to Java classes for complex schema definitions.
456

457
```java { .api }
458
/**
459
 * Maps strings to classes for schema definitions
460
 */
461
@StringToClassMapItem(
462
    key = "userType",                                // String key
463
    value = User.class                               // Mapped class
464
)
465
```
466

467
## Enum Reference
468

469
### Explode Behavior
470

471
```java { .api }
472
enum Explode {
473
    DEFAULT,    // Use parameter style default
474
    FALSE,      // Don't explode array/object values  
475
    TRUE        // Explode array/object values
476
}
477
```
478

479
### OpenAPI 3.1 Marker
480

481
```java { .api }
482
/**
483
 * Marker annotation for OpenAPI 3.1 specific features
484
 * Applied to: various elements supporting 3.1 features
485
 */
486
@OpenAPI31
487
```