0
# Security Documentation
1

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

4
## Capabilities
5

6
### @Authorization Annotation
7

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

10
```java { .api }
11
/**
12
 * Defines authorization scheme usage
13
 * Target: METHOD
14
 * Retention: RUNTIME
15
 */
16
@Target(ElementType.METHOD)
17
@Retention(RetentionPolicy.RUNTIME)
18
@interface Authorization {
19
    /**
20
     * Name of the authorization scheme
21
     * Must match a key in SecurityDefinition
22
     * REQUIRED ATTRIBUTE
23
     */
24
    String value();
25
    
26
    /**
27
     * OAuth2 scopes required for this authorization
28
     * Only used with OAuth2 security schemes
29
     * Empty array means no specific scopes required
30
     */
31
    AuthorizationScope[] scopes() default @AuthorizationScope(scope = "", description = "");
32
}
33
```
34

35
**Usage Examples:**
36

37
```java
38
// Basic authorization reference
39
@ApiOperation(
40
    value = "Get user profile",
41
    authorizations = @Authorization(value = "api_key")
42
)
43
@GET
44
@Path("/profile")
45
public User getUserProfile() {
46
    // implementation
47
}
48

49
// OAuth2 with specific scopes
50
@ApiOperation(
51
    value = "Delete user account",
52
    authorizations = @Authorization(
53
        value = "oauth2", 
54
        scopes = {
55
            @AuthorizationScope(scope = "user:delete", description = "Delete user accounts"),
56
            @AuthorizationScope(scope = "admin", description = "Administrative access")
57
        }
58
    )
59
)
60
@DELETE
61
@Path("/users/{id}")
62
public Response deleteUser(@PathParam("id") Long id) {
63
    // implementation
64
}
65

66
// Multiple authorization schemes (OR relationship)
67
@ApiOperation(
68
    value = "Access admin panel",
69
    authorizations = {
70
        @Authorization(value = "oauth2", scopes = {
71
            @AuthorizationScope(scope = "admin", description = "Admin access")
72
        }),
73
        @Authorization(value = "admin_key")
74
    }
75
)
76
@GET
77
@Path("/admin")
78
public AdminDashboard getAdminDashboard() {
79
    // implementation
80
}
81
```
82

83
### @AuthorizationScope Annotation
84

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

87
```java { .api }
88
/**
89
 * Describes OAuth2 authorization scope
90
 * Target: METHOD
91
 * Retention: RUNTIME
92
 */
93
@Target(ElementType.METHOD)
94
@Retention(RetentionPolicy.RUNTIME)
95
@interface AuthorizationScope {
96
    /**
97
     * OAuth2 scope name
98
     * Should match scope names defined in OAuth2Definition
99
     * REQUIRED ATTRIBUTE
100
     */
101
    String scope();
102
    
103
    /**
104
     * Scope description for documentation
105
     * Provides human-readable explanation of scope permissions
106
     * REQUIRED ATTRIBUTE (legacy support)
107
     */
108
    String description();
109
}
110
```
111

112
**Usage Examples:**
113

114
```java
115
// Read-only access scope
116
@AuthorizationScope(scope = "read", description = "Read-only access to resources")
117

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

121
// Admin scope with detailed description
122
@AuthorizationScope(
123
    scope = "admin", 
124
    description = "Full administrative access including user management and system configuration"
125
)
126

127
// Resource-specific scopes
128
@AuthorizationScope(scope = "user:profile:read", description = "Read user profile information")
129
@AuthorizationScope(scope = "user:profile:write", description = "Modify user profile information")
130
@AuthorizationScope(scope = "user:delete", description = "Delete user accounts")
131
```
132

133
### @SecurityDefinition Annotation
134

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

137
```java { .api }
138
/**
139
 * Aggregates all security definitions
140
 * Target: ANNOTATION_TYPE
141
 * Retention: RUNTIME
142
 */
143
@Target(ElementType.ANNOTATION_TYPE)
144
@Retention(RetentionPolicy.RUNTIME)
145
@interface SecurityDefinition {
146
    /**
147
     * OAuth2 security definitions
148
     * Array of OAuth2 authentication schemes
149
     */
150
    OAuth2Definition[] oAuth2Definitions() default {};
151
    
152
    /**
153
     * API Key security definitions
154
     * Array of API Key authentication schemes
155
     */
156
    ApiKeyAuthDefinition[] apiKeyAuthDefinitions() default {};
157
    
158
    /** @deprecated Typo in attribute name, use apiKeyAuthDefinitions() instead */
159
    ApiKeyAuthDefinition[] apiKeyAuthDefintions() default {};
160
    
161
    /**
162
     * Basic Authentication security definitions
163
     * Array of Basic Auth schemes
164
     */
165
    BasicAuthDefinition[] basicAuthDefinitions() default {};
166
    
167
    /** @deprecated Typo in attribute name, use basicAuthDefinitions() instead */
168
    BasicAuthDefinition[] basicAuthDefinions() default {};
169
}
170
```
171

172
**Usage Examples:**
173

174
```java
175
// Complete security definition with multiple schemes
176
@SwaggerDefinition(
177
    info = @Info(title = "Secure API", version = "1.0"),
178
    securityDefinition = @SecurityDefinition(
179
        oAuth2Definitions = {
180
            @OAuth2Definition(
181
                key = "oauth2",
182
                description = "OAuth2 authentication",
183
                flow = OAuth2Definition.Flow.AUTHORIZATION_CODE,
184
                authorizationUrl = "https://auth.example.com/oauth/authorize",
185
                tokenUrl = "https://auth.example.com/oauth/token",
186
                scopes = {
187
                    @Scope(name = "read", description = "Read access"),
188
                    @Scope(name = "write", description = "Write access"),
189
                    @Scope(name = "admin", description = "Administrative access")
190
                }
191
            )
192
        },
193
        apiKeyAuthDefinitions = {
194
            @ApiKeyAuthDefinition(
195
                key = "api_key",
196
                description = "API Key authentication",
197
                in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
198
                name = "X-API-Key"
199
            ),
200
            @ApiKeyAuthDefinition(
201
                key = "query_key",
202
                description = "API Key in query parameter",
203
                in = ApiKeyAuthDefinition.ApiKeyLocation.QUERY,
204
                name = "api_key"
205
            )
206
        },
207
        basicAuthDefinitions = {
208
            @BasicAuthDefinition(
209
                key = "basic_auth",
210
                description = "HTTP Basic Authentication"
211
            )
212
        }
213
    )
214
)
215
public class SecureApiConfig {
216
}
217

218
// Simple API key only setup
219
@SwaggerDefinition(
220
    info = @Info(title = "Simple API", version = "1.0"),
221
    securityDefinition = @SecurityDefinition(
222
        apiKeyAuthDefinitions = @ApiKeyAuthDefinition(
223
            key = "api_key",
224
            description = "Simple API Key authentication",
225
            in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
226
            name = "Authorization"
227
        )
228
    )
229
)
230
public class SimpleApiConfig {
231
}
232
```
233

234
### @OAuth2Definition Annotation
235

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

238
```java { .api }
239
/**
240
 * Constructs OAuth2 security definition
241
 * No @Target annotation (used within other annotations)
242
 * Retention: RUNTIME
243
 */
244
@Retention(RetentionPolicy.RUNTIME)
245
@interface OAuth2Definition {
246
    /**
247
     * Security definition key
248
     * Referenced by @Authorization value
249
     * REQUIRED ATTRIBUTE
250
     */
251
    String key();
252
    
253
    /**
254
     * Security scheme description
255
     * Human-readable description of the OAuth2 scheme
256
     */
257
    String description() default "";
258
    
259
    /**
260
     * OAuth2 flow type
261
     * Determines which URLs are required
262
     * REQUIRED ATTRIBUTE
263
     */
264
    Flow flow();
265
    
266
    /**
267
     * Authorization URL for implicit/authorization code flows
268
     * Required for IMPLICIT and ACCESS_CODE flows
269
     * Ignored for PASSWORD and APPLICATION flows
270
     */
271
    String authorizationUrl() default "";
272
    
273
    /**
274
     * Token URL for password/application/authorization code flows
275
     * Required for PASSWORD, APPLICATION, and ACCESS_CODE flows
276
     * Ignored for IMPLICIT flow
277
     */
278
    String tokenUrl() default "";
279
    
280
    /**
281
     * Available OAuth2 scopes
282
     * Defines permissions that can be requested
283
     */
284
    Scope[] scopes() default {};
285
    
286
    /**
287
     * OAuth2 Flow enumeration
288
     */
289
    enum Flow {
290
        IMPLICIT,        // Implicit grant flow
291
        ACCESS_CODE,     // Authorization code flow  
292
        PASSWORD,        // Resource owner password credentials flow
293
        APPLICATION      // Client credentials flow
294
    }
295
}
296
```
297

298
**Usage Examples:**
299

300
```java
301
// Authorization Code Flow (most secure for web applications)
302
@OAuth2Definition(
303
    key = "oauth2_auth_code",
304
    description = "OAuth2 Authorization Code Flow",
305
    flow = OAuth2Definition.Flow.ACCESS_CODE,
306
    authorizationUrl = "https://auth.example.com/oauth/authorize",
307
    tokenUrl = "https://auth.example.com/oauth/token",
308
    scopes = {
309
        @Scope(name = "read", description = "Read access to resources"),
310
        @Scope(name = "write", description = "Write access to resources"),
311
        @Scope(name = "admin", description = "Full administrative access")
312
    }
313
)
314

315
// Implicit Flow (for client-side applications)
316
@OAuth2Definition(
317
    key = "oauth2_implicit",
318
    description = "OAuth2 Implicit Flow for JavaScript clients",
319
    flow = OAuth2Definition.Flow.IMPLICIT,
320
    authorizationUrl = "https://auth.example.com/oauth/authorize",
321
    scopes = {
322
        @Scope(name = "profile", description = "Access to user profile"),
323
        @Scope(name = "email", description = "Access to user email")
324
    }
325
)
326

327
// Client Credentials Flow (for server-to-server)
328
@OAuth2Definition(
329
    key = "oauth2_client_credentials", 
330
    description = "OAuth2 Client Credentials for service authentication",
331
    flow = OAuth2Definition.Flow.APPLICATION,
332
    tokenUrl = "https://auth.example.com/oauth/token",
333
    scopes = {
334
        @Scope(name = "service:read", description = "Read access for services"),
335
        @Scope(name = "service:write", description = "Write access for services")
336
    }
337
)
338

339
// Password Flow (for trusted applications)
340
@OAuth2Definition(
341
    key = "oauth2_password",
342
    description = "OAuth2 Resource Owner Password Flow",
343
    flow = OAuth2Definition.Flow.PASSWORD,
344
    tokenUrl = "https://auth.example.com/oauth/token",
345
    scopes = {
346
        @Scope(name = "full_access", description = "Complete access to user resources")
347
    }
348
)
349
```
350

351
### @ApiKeyAuthDefinition Annotation
352

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

355
```java { .api }
356
/**
357
 * Constructs API Key authentication definition
358
 * No @Target annotation (used within other annotations)
359
 * Retention: RUNTIME
360
 */
361
@Retention(RetentionPolicy.RUNTIME)
362
@interface ApiKeyAuthDefinition {
363
    /**
364
     * Security definition key
365
     * Referenced by @Authorization value
366
     * REQUIRED ATTRIBUTE
367
     */
368
    String key();
369
    
370
    /**
371
     * Security scheme description
372
     * Human-readable description of the API key scheme
373
     */
374
    String description() default "";
375
    
376
    /**
377
     * Key location (header or query parameter)
378
     * Determines how the API key is transmitted
379
     * REQUIRED ATTRIBUTE
380
     */
381
    ApiKeyLocation in();
382
    
383
    /**
384
     * Header or query parameter name
385
     * Name of the field containing the API key
386
     * REQUIRED ATTRIBUTE
387
     */
388
    String name();
389
    
390
    /**
391
     * API Key Location enumeration
392
     */
393
    enum ApiKeyLocation {
394
        HEADER("header"),
395
        QUERY("query");
396
        
397
        private final String value;
398
        
399
        ApiKeyLocation(String value) {
400
            this.value = value;
401
        }
402
        
403
        public static ApiKeyLocation forValue(String value) {
404
            // Returns enum for string value
405
        }
406
        
407
        public String toValue() {
408
            return value;
409
        }
410
    }
411
}
412
```
413

414
**Usage Examples:**
415

416
```java
417
// Standard Authorization header
418
@ApiKeyAuthDefinition(
419
    key = "bearer_token",
420
    description = "Bearer token authentication",
421
    in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
422
    name = "Authorization"
423
)
424

425
// Custom header API key
426
@ApiKeyAuthDefinition(
427
    key = "api_key_header",
428
    description = "Custom API key in header",
429
    in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
430
    name = "X-API-Key"
431
)
432

433
// Query parameter API key
434
@ApiKeyAuthDefinition(
435
    key = "api_key_query",
436
    description = "API key as query parameter",
437
    in = ApiKeyAuthDefinition.ApiKeyLocation.QUERY,
438
    name = "key"
439
)
440

441
// Multiple API key definitions for different use cases
442
@SecurityDefinition(
443
    apiKeyAuthDefinitions = {
444
        @ApiKeyAuthDefinition(
445
            key = "user_token",
446
            description = "User authentication token",
447
            in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
448
            name = "X-User-Token"
449
        ),
450
        @ApiKeyAuthDefinition(
451
            key = "app_key",
452
            description = "Application API key",
453
            in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,  
454
            name = "X-App-Key"
455
        ),
456
        @ApiKeyAuthDefinition(
457
            key = "legacy_key",
458
            description = "Legacy API key for backward compatibility",
459
            in = ApiKeyAuthDefinition.ApiKeyLocation.QUERY,
460
            name = "api_key"
461
        )
462
    }
463
)
464
```
465

466
### @BasicAuthDefinition Annotation
467

468
Constructs Basic Authentication definitions. Represents HTTP Basic Authentication scheme.
469

470
```java { .api }
471
/**
472
 * Constructs Basic Authentication definition
473
 * No @Target annotation (used within other annotations)
474
 * Retention: RUNTIME
475
 */
476
@Retention(RetentionPolicy.RUNTIME)
477
@interface BasicAuthDefinition {
478
    /**
479
     * Security definition key
480
     * Referenced by @Authorization value
481
     * REQUIRED ATTRIBUTE
482
     */
483
    String key();
484
    
485
    /**
486
     * Security scheme description
487
     * Human-readable description of the Basic Auth scheme
488
     */
489
    String description() default "";
490
}
491
```
492

493
**Usage Examples:**
494

495
```java
496
// Simple Basic Authentication
497
@BasicAuthDefinition(
498
    key = "basic_auth",
499
    description = "HTTP Basic Authentication"
500
)
501

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

508
// Multiple Basic Auth schemes for different purposes
509
@SecurityDefinition(
510
    basicAuthDefinitions = {
511
        @BasicAuthDefinition(
512
            key = "user_basic",
513
            description = "Basic Authentication for regular users"
514
        ),
515
        @BasicAuthDefinition(
516
            key = "admin_basic", 
517
            description = "Basic Authentication for administrators"
518
        )
519
    }
520
)
521

522
// Combined with other authentication methods
523
@SecurityDefinition(
524
    basicAuthDefinitions = @BasicAuthDefinition(
525
        key = "basic_auth",
526
        description = "Fallback Basic Authentication"
527
    ),
528
    apiKeyAuthDefinitions = @ApiKeyAuthDefinition(
529
        key = "api_key",
530
        description = "Preferred API Key authentication", 
531
        in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
532
        name = "X-API-Key"
533
    )
534
)
535
```
536

537
### @Scope Annotation (Enum)
538

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

541
```java { .api }
542
/**
543
 * Defines OAuth2 scope
544
 * No @Target annotation (used within other annotations)
545
 * Retention: RUNTIME
546
 */
547
@Retention(RetentionPolicy.RUNTIME)
548
@interface Scope {
549
    /**
550
     * Scope name
551
     * Unique identifier for the permission scope
552
     * REQUIRED ATTRIBUTE
553
     */
554
    String name();
555
    
556
    /**
557
     * Scope description
558
     * Human-readable explanation of what the scope grants
559
     * REQUIRED ATTRIBUTE
560
     */
561
    String description();
562
}
563
```
564

565
**Usage Examples:**
566

567
```java
568
// Standard CRUD scopes
569
@Scope(name = "read", description = "Read access to resources")
570
@Scope(name = "write", description = "Create and modify resources") 
571
@Scope(name = "delete", description = "Delete resources")
572

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

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

584
// System-level scopes
585
@Scope(name = "system:config", description = "Access system configuration")
586
@Scope(name = "system:monitoring", description = "Access monitoring and metrics")
587
@Scope(name = "system:backup", description = "Perform system backups")
588
```
589

590
## Complex Security Scenarios
591

592
### Multi-Tier Authentication
593

594
```java
595
// API with multiple authentication options
596
@SwaggerDefinition(
597
    info = @Info(title = "Enterprise API", version = "2.0"),
598
    securityDefinition = @SecurityDefinition(
599
        oAuth2Definitions = @OAuth2Definition(
600
            key = "enterprise_oauth",
601
            description = "Enterprise OAuth2 with comprehensive scopes",
602
            flow = OAuth2Definition.Flow.ACCESS_CODE,
603
            authorizationUrl = "https://auth.enterprise.com/oauth/authorize",
604
            tokenUrl = "https://auth.enterprise.com/oauth/token",
605
            scopes = {
606
                @Scope(name = "employee:read", description = "Read employee data"),
607
                @Scope(name = "employee:write", description = "Modify employee data"),
608
                @Scope(name = "payroll:read", description = "Access payroll information"),
609
                @Scope(name = "payroll:process", description = "Process payroll"),
610
                @Scope(name = "hr:admin", description = "HR administrative functions"),
611
                @Scope(name = "system:admin", description = "System administration")
612
            }
613
        ),
614
        apiKeyAuthDefinitions = {
615
            @ApiKeyAuthDefinition(
616
                key = "service_key",
617
                description = "Service-to-service authentication",
618
                in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
619
                name = "X-Service-Key"
620
            ),
621
            @ApiKeyAuthDefinition(
622
                key = "integration_key",
623
                description = "Third-party integration key", 
624
                in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
625
                name = "X-Integration-Key"
626
            )
627
        },
628
        basicAuthDefinitions = @BasicAuthDefinition(
629
            key = "emergency_access",
630
            description = "Emergency access when OAuth is unavailable"
631
        )
632
    )
633
)
634
public class EnterpriseApiConfig {
635
}
636

637
// Operations with different security requirements
638
@Api(tags = "employees")
639
@Path("/employees")
640
public class EmployeeController {
641

642
    @ApiOperation(
643
        value = "List employees",
644
        authorizations = {
645
            @Authorization(value = "enterprise_oauth", scopes = {
646
                @AuthorizationScope(scope = "employee:read", description = "Read employee data")
647
            }),
648
            @Authorization(value = "service_key")
649
        }
650
    )
651
    @GET
652
    public List<Employee> listEmployees() {
653
        // Accessible via OAuth with employee:read scope OR service key
654
    }
655
    
656
    @ApiOperation(
657
        value = "Process payroll",
658
        authorizations = @Authorization(value = "enterprise_oauth", scopes = {
659
            @AuthorizationScope(scope = "payroll:process", description = "Process payroll"),
660
            @AuthorizationScope(scope = "hr:admin", description = "HR admin required for payroll")
661
        })
662
    )
663
    @POST
664
    @Path("/payroll/process")
665
    public Response processPayroll() {
666
        // Requires BOTH payroll:process AND hr:admin scopes
667
    }
668
    
669
    @ApiOperation(
670
        value = "Emergency employee access",
671
        authorizations = @Authorization(value = "emergency_access")
672
    )
673
    @GET
674
    @Path("/emergency/{id}")
675
    public Employee getEmployeeEmergency(@PathParam("id") Long id) {
676
        // Basic auth only for emergency situations
677
    }
678
}
679
```
680

681
### Microservices Security Architecture
682

683
```java
684
// Gateway service security configuration
685
@SwaggerDefinition(
686
    info = @Info(title = "API Gateway", version = "1.0"),
687
    securityDefinition = @SecurityDefinition(
688
        oAuth2Definitions = {
689
            @OAuth2Definition(
690
                key = "user_oauth",
691
                description = "User authentication flow",
692
                flow = OAuth2Definition.Flow.AUTHORIZATION_CODE,
693
                authorizationUrl = "https://auth.company.com/oauth/authorize",
694
                tokenUrl = "https://auth.company.com/oauth/token", 
695
                scopes = {
696
                    @Scope(name = "profile", description = "Basic profile access"),
697
                    @Scope(name = "email", description = "Email access"),
698
                    @Scope(name = "premium", description = "Premium features access")
699
                }
700
            ),
701
            @OAuth2Definition(
702
                key = "service_oauth",
703
                description = "Service-to-service authentication",
704
                flow = OAuth2Definition.Flow.APPLICATION,
705
                tokenUrl = "https://auth.company.com/oauth/token",
706
                scopes = {
707
                    @Scope(name = "service:read", description = "Inter-service read access"),
708
                    @Scope(name = "service:write", description = "Inter-service write access"),
709
                    @Scope(name = "service:admin", description = "Service administration")
710
                }
711
            )
712
        },
713
        apiKeyAuthDefinitions = {
714
            @ApiKeyAuthDefinition(
715
                key = "gateway_key",
716
                description = "Gateway bypass key for internal services",
717
                in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
718
                name = "X-Gateway-Key"
719
            ),
720
            @ApiKeyAuthDefinition(
721
                key = "webhook_key",
722
                description = "Webhook authentication key",
723
                in = ApiKeyAuthDefinition.ApiKeyLocation.QUERY,
724
                name = "webhook_key"
725
            )
726
        }
727
    )
728
)
729
public class GatewayApiConfig {
730
}
731

732
// User-facing endpoints
733
@Api(tags = "user-api")
734
@Path("/api/user")
735
public class UserApiController {
736
    
737
    @ApiOperation(
738
        value = "Get user profile",
739
        authorizations = @Authorization(value = "user_oauth", scopes = {
740
            @AuthorizationScope(scope = "profile", description = "Access to user profile")
741
        })
742
    )
743
    @GET
744
    @Path("/profile")
745
    public UserProfile getUserProfile() {
746
        // User OAuth with profile scope
747
    }
748
    
749
    @ApiOperation(
750
        value = "Access premium features",
751
        authorizations = @Authorization(value = "user_oauth", scopes = {
752
            @AuthorizationScope(scope = "premium", description = "Premium features access")
753
        })
754
    )
755
    @GET
756
    @Path("/premium")
757
    public PremiumFeatures getPremiumFeatures() {
758
        // Requires premium scope
759
    }
760
}
761

762
// Internal service endpoints  
763
@Api(tags = "internal-api")
764
@Path("/internal")
765
public class InternalApiController {
766
    
767
    @ApiOperation(
768
        value = "Service health check",
769
        authorizations = {
770
            @Authorization(value = "service_oauth", scopes = {
771
                @AuthorizationScope(scope = "service:read", description = "Service read access")
772
            }),
773
            @Authorization(value = "gateway_key")
774
        }
775
    )
776
    @GET
777
    @Path("/health")
778
    public HealthStatus getHealthStatus() {
779
        // Service OAuth OR gateway key
780
    }
781
    
782
    @ApiOperation(
783
        value = "Update service configuration", 
784
        authorizations = @Authorization(value = "service_oauth", scopes = {
785
            @AuthorizationScope(scope = "service:admin", description = "Service administration")
786
        })
787
    )
788
    @PUT
789
    @Path("/config")
790
    public Response updateConfiguration(ServiceConfig config) {
791
        // Requires service admin scope
792
    }
793
}
794

795
// Webhook endpoints
796
@Api(tags = "webhooks")
797
@Path("/webhooks")
798
public class WebhookController {
799
    
800
    @ApiOperation(
801
        value = "Payment webhook",
802
        authorizations = @Authorization(value = "webhook_key")
803
    )
804
    @POST
805
    @Path("/payment")
806
    public Response handlePaymentWebhook(PaymentEvent event) {
807
        // Webhook key in query parameter
808
    }
809
}
810
```
811

812
## Best Practices
813

814
### Security Definition Strategy
815

816
1. **Use descriptive keys** - Choose clear, meaningful names for security definition keys
817
2. **Provide detailed descriptions** - Help developers understand authentication requirements
818
3. **Organize by purpose** - Group related security schemes logically
819
4. **Plan for multiple environments** - Consider different auth URLs for dev/staging/prod
820

821
### OAuth2 Implementation
822

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

828
### API Key Management
829

830
1. **Use headers over query parameters** - More secure transmission method
831
2. **Choose descriptive parameter names** - Clear field names improve developer experience
832
3. **Support multiple key types** - Different keys for different use cases (user vs service)
833
4. **Document key formats** - Specify expected key structure or encoding
834

835
### Authorization Patterns
836

837
1. **Principle of least privilege** - Require only necessary scopes for each operation
838
2. **Provide alternatives** - Offer multiple authentication methods when appropriate
839
3. **Document security implications** - Explain what each authorization grants access to
840
4. **Consider operation sensitivity** - Apply stricter requirements for dangerous operations
841

842
### Documentation Guidelines
843

844
1. **Include realistic examples** - Show actual usage patterns developers will encounter
845
2. **Explain scope combinations** - Document when multiple scopes are required
846
3. **Provide troubleshooting info** - Help developers diagnose authentication issues
847
4. **Keep security descriptions current** - Update documentation when auth schemes change