0
# Server and API Information
1

2
Server definitions, API metadata, contact information, external documentation, and tags configuration. This system provides comprehensive API information management including multi-environment server configuration, detailed API metadata, and organizational features.
3

4
## Capabilities
5

6
### Server Configuration
7

8
Defines server connectivity information with URL templates and environment variables.
9

10
```java { .api }
11
/**
12
 * Defines server connectivity information
13
 * Applied to: TYPE, METHOD (for operation-specific servers)
14
 * Repeatable: Yes
15
 */
16
@Server(
17
    url = "https://api.{environment}.example.com",  // Server URL with variables (required)
18
    description = "Main API server",                // Server description
19
    variables = {                                   // URL template variables
20
        @ServerVariable(
21
            name = "environment",
22
            defaultValue = "prod",
23
            allowableValues = {"dev", "staging", "prod"},
24
            description = "Deployment environment"
25
        ),
26
        @ServerVariable(
27
            name = "version",
28
            defaultValue = "v1", 
29
            allowableValues = {"v1", "v2"},
30
            description = "API version"
31
        )
32
    },
33
    extensions = {@Extension(...)}                  // Custom extensions
34
)
35

36
/**
37
 * Defines server URL template variables
38
 */
39
@ServerVariable(
40
    name = "environment",                           // Variable name (required)
41
    defaultValue = "prod",                          // Default value (required)
42
    allowableValues = {"dev", "staging", "prod"},   // Allowed values (optional)
43
    description = "Environment identifier",         // Variable description
44
    extensions = {@Extension(...)}                  // Custom extensions
45
)
46
```
47

48
**Usage Examples:**
49

50
```java
51
// Single server
52
@OpenAPIDefinition(
53
    info = @Info(title = "API", version = "1.0"),
54
    servers = @Server(
55
        url = "https://api.example.com",
56
        description = "Production server"
57
    )
58
)
59

60
// Multiple servers with environments
61
@OpenAPIDefinition(
62
    info = @Info(title = "Multi-Environment API", version = "2.0"),
63
    servers = {
64
        @Server(
65
            url = "https://api.{environment}.example.com",
66
            description = "Environment-specific server",
67
            variables = @ServerVariable(
68
                name = "environment",
69
                defaultValue = "prod",
70
                allowableValues = {"dev", "staging", "prod"},
71
                description = "Deployment environment"
72
            )
73
        ),
74
        @Server(
75
            url = "https://localhost:{port}",
76
            description = "Local development server",
77
            variables = @ServerVariable(
78
                name = "port",
79
                defaultValue = "8080",
80
                allowableValues = {"8080", "3000", "9000"},
81
                description = "Port number"
82
            )
83
        )
84
    }
85
)
86

87
// Regional servers
88
@OpenAPIDefinition(
89
    servers = {
90
        @Server(
91
            url = "https://api-{region}.example.com",
92
            description = "Regional API server",
93
            variables = @ServerVariable(
94
                name = "region",
95
                defaultValue = "us-east",
96
                allowableValues = {"us-east", "us-west", "eu-central", "ap-southeast"},
97
                description = "Geographic region"
98
            )
99
        ),
100
        @Server(
101
            url = "https://api.example.com",
102
            description = "Global load balancer"
103
        )
104
    }
105
)
106

107
// Operation-specific server override
108
@POST
109
@Path("/special")
110
@Operation(
111
    summary = "Special operation using different server",
112
    servers = @Server(
113
        url = "https://special-api.example.com",
114
        description = "Specialized processing server"
115
    )
116
)
117
public Response specialOperation() {}
118

119
// Complex server variables
120
@Server(
121
    url = "https://{customer}.{environment}.example.com:{port}/{basePath}",
122
    description = "Multi-tenant server with custom base path",
123
    variables = {
124
        @ServerVariable(
125
            name = "customer",
126
            defaultValue = "default",
127
            description = "Customer tenant identifier"
128
        ),
129
        @ServerVariable(
130
            name = "environment", 
131
            defaultValue = "prod",
132
            allowableValues = {"dev", "staging", "prod"}
133
        ),
134
        @ServerVariable(
135
            name = "port",
136
            defaultValue = "443",
137
            allowableValues = {"80", "443", "8443"}
138
        ),
139
        @ServerVariable(
140
            name = "basePath",
141
            defaultValue = "api/v1",
142
            description = "API base path"
143
        )
144
    }
145
)
146
```
147

148
### Servers Container
149

150
Container for multiple server definitions.
151

152
```java { .api }
153
/**
154
 * Container for multiple Server annotations
155
 */
156
@Servers({
157
    @Server(url = "https://api.example.com", description = "Production"),
158
    @Server(url = "https://staging-api.example.com", description = "Staging"),
159
    @Server(url = "http://localhost:8080", description = "Development")
160
})
161
```
162

163
### API Information
164

165
Comprehensive API metadata including title, version, description, contact, and license information.
166

167
```java { .api }
168
/**
169
 * Defines API metadata information
170
 * Applied to: within OpenAPIDefinition
171
 */
172
@Info(
173
    title = "User Management API",                  // API title (required)
174
    version = "2.1.0",                             // API version (required)
175
    description = "Complete user management system with authentication and authorization", // API description
176
    summary = "User management and authentication API", // Short API summary (OpenAPI 3.1)
177
    termsOfService = "https://example.com/terms",   // Terms of service URL
178
    contact = @Contact(...),                        // Contact information
179
    license = @License(...),                        // License information
180
    extensions = {@Extension(...)}                  // Custom extensions
181
)
182
```
183

184
**Usage Examples:**
185

186
```java
187
// Basic API info
188
@Info(
189
    title = "E-Commerce API",
190
    version = "3.0.0",
191
    description = "RESTful API for e-commerce operations including products, orders, and payments"
192
)
193

194
// Complete API info with contact and license
195
@Info(
196
    title = "Enterprise User API",
197
    version = "2.5.1",
198
    description = """
199
        Comprehensive user management API providing:
200
        - User account creation and management
201
        - Authentication and authorization
202
        - Role-based access control
203
        - Profile management
204
        - Activity tracking
205
        """,
206
    summary = "Enterprise-grade user management API",
207
    termsOfService = "https://example.com/api/terms",
208
    contact = @Contact(
209
        name = "API Support Team",
210
        email = "api-support@example.com",
211
        url = "https://example.com/support"
212
    ),
213
    license = @License(
214
        name = "Apache License 2.0",
215
        url = "https://www.apache.org/licenses/LICENSE-2.0.html",
216
        identifier = "Apache-2.0"
217
    ),
218
    extensions = {
219
        @Extension(
220
            name = "x-api-category",
221
            properties = @ExtensionProperty(name = "category", value = "user-management")
222
        ),
223
        @Extension(
224
            name = "x-maturity-level",
225
            properties = @ExtensionProperty(name = "level", value = "stable")
226
        )
227
    }
228
)
229
```
230

231
### Contact Information
232

233
Defines contact information for the API.
234

235
```java { .api }
236
/**
237
 * Defines contact information for the API
238
 * Applied to: within Info annotation
239
 */
240
@Contact(
241
    name = "API Support Team",                      // Contact name
242
    email = "support@example.com",                  // Contact email
243
    url = "https://example.com/support",           // Contact URL
244
    extensions = {@Extension(...)}                  // Custom extensions
245
)
246
```
247

248
**Usage Examples:**
249

250
```java
251
// Basic contact
252
@Contact(
253
    name = "Development Team",
254
    email = "dev@example.com"
255
)
256

257
// Complete contact with support portal
258
@Contact(
259
    name = "API Support",
260
    email = "api-support@example.com",
261
    url = "https://support.example.com/api",
262
    extensions = @Extension(
263
        name = "x-support-hours",
264
        properties = {
265
            @ExtensionProperty(name = "timezone", value = "UTC"),
266
            @ExtensionProperty(name = "hours", value = "24/7"),
267
            @ExtensionProperty(name = "sla", value = "4-hour response")
268
        }
269
    )
270
)
271

272
// Team contact with multiple channels
273
@Contact(
274
    name = "Platform Team",
275
    email = "platform@example.com",
276
    url = "https://example.com/platform-team",
277
    extensions = {
278
        @Extension(
279
            name = "x-contact-channels",
280
            properties = {
281
                @ExtensionProperty(name = "slack", value = "#platform-support"),
282
                @ExtensionProperty(name = "phone", value = "+1-555-0123"),
283
                @ExtensionProperty(name = "hours", value = "9 AM - 5 PM EST")
284
            }
285
        )
286
    }
287
)
288
```
289

290
### License Information
291

292
Defines license information for the API.
293

294
```java { .api }
295
/**
296
 * Defines license information for the API
297
 * Applied to: within Info annotation
298
 */
299
@License(
300
    name = "Apache License 2.0",                   // License name (required)
301
    url = "https://www.apache.org/licenses/LICENSE-2.0.html", // License URL
302
    identifier = "Apache-2.0",                     // SPDX license identifier (OpenAPI 3.1)
303
    extensions = {@Extension(...)}                  // Custom extensions
304
)
305
```
306

307
**Usage Examples:**
308

309
```java
310
// MIT License
311
@License(
312
    name = "MIT License",
313
    url = "https://opensource.org/licenses/MIT",
314
    identifier = "MIT"
315
)
316

317
// Apache License with additional info
318
@License(
319
    name = "Apache License, Version 2.0",
320
    url = "https://www.apache.org/licenses/LICENSE-2.0.html",
321
    identifier = "Apache-2.0",
322
    extensions = @Extension(
323
        name = "x-license-info",
324
        properties = {
325
            @ExtensionProperty(name = "attribution", value = "Required"),
326
            @ExtensionProperty(name = "commercial-use", value = "Allowed"),
327
            @ExtensionProperty(name = "modification", value = "Allowed")
328
        }
329
    )
330
)
331

332
// Custom license
333
@License(
334
    name = "Custom Enterprise License",
335
    url = "https://example.com/licenses/enterprise",
336
    extensions = @Extension(
337
        name = "x-license-type",
338
        properties = @ExtensionProperty(name = "type", value = "proprietary")
339
    )
340
)
341

342
// GPL License
343
@License(
344
    name = "GNU General Public License v3.0",
345
    url = "https://www.gnu.org/licenses/gpl-3.0.html",
346
    identifier = "GPL-3.0"
347
)
348
```
349

350
### Tag Definitions
351

352
Defines tags for logical grouping of operations with metadata and external documentation.
353

354
```java { .api }
355
/**
356
 * Defines tag for operation grouping
357
 * Applied to: TYPE (global tags), METHOD (operation tags)
358
 * Repeatable: Yes
359
 */
360
@Tag(
361
    name = "users",                                 // Tag name (required)
362
    description = "User management operations",     // Tag description
363
    externalDocs = @ExternalDocumentation(          // External documentation
364
        description = "User Management Guide",
365
        url = "https://docs.example.com/users"
366
    ),
367
    extensions = {@Extension(...)}                  // Custom extensions
368
)
369
```
370

371
**Usage Examples:**
372

373
```java
374
// Global tags definition
375
@OpenAPIDefinition(
376
    info = @Info(title = "API", version = "1.0"),
377
    tags = {
378
        @Tag(
379
            name = "users",
380
            description = "User account management and authentication",
381
            externalDocs = @ExternalDocumentation(
382
                description = "User Guide",
383
                url = "https://docs.example.com/user-guide"
384
            )
385
        ),
386
        @Tag(
387
            name = "products",
388
            description = "Product catalog and inventory management",
389
            externalDocs = @ExternalDocumentation(
390
                description = "Product Management Guide", 
391
                url = "https://docs.example.com/products"
392
            )
393
        ),
394
        @Tag(
395
            name = "orders",
396
            description = "Order processing and fulfillment"
397
        ),
398
        @Tag(
399
            name = "admin",
400
            description = "Administrative operations",
401
            extensions = @Extension(
402
                name = "x-audience",
403
                properties = @ExtensionProperty(name = "audience", value = "internal")
404
            )
405
        )
406
    }
407
)
408

409
// Operation with multiple tags
410
@GET
411
@Path("/user/{id}/orders")
412
@Operation(
413
    summary = "Get user orders",
414
    tags = {"users", "orders"}
415
)
416
public Response getUserOrders(@PathParam("id") Long userId) {}
417

418
// Tag with detailed metadata
419
@Tag(
420
    name = "authentication",
421
    description = "Authentication and authorization endpoints",
422
    externalDocs = @ExternalDocumentation(
423
        description = "Authentication Guide",
424
        url = "https://docs.example.com/auth"
425
    ),
426
    extensions = {
427
        @Extension(
428
            name = "x-tag-metadata",
429
            properties = {
430
                @ExtensionProperty(name = "stability", value = "stable"),
431
                @ExtensionProperty(name = "audience", value = "public"),
432
                @ExtensionProperty(name = "rate-limit", value = "strict")
433
            }
434
        )
435
    }
436
)
437
```
438

439
### Tags Container
440

441
Container for multiple tag definitions.
442

443
```java { .api }
444
/**
445
 * Container for multiple Tag annotations
446
 */
447
@Tags({
448
    @Tag(name = "users", description = "User operations"),
449
    @Tag(name = "products", description = "Product operations"),
450
    @Tag(name = "orders", description = "Order operations"),
451
    @Tag(name = "admin", description = "Administrative operations")
452
})
453
```
454

455
### External Documentation
456

457
Defines references to external documentation for various API elements.
458

459
```java { .api }
460
/**
461
 * Defines external documentation reference
462
 * Applied to: various annotation elements
463
 */
464
@ExternalDocumentation(
465
    description = "Complete API documentation",     // Description (required)
466
    url = "https://docs.example.com/api",          // Documentation URL (required)
467
    extensions = {@Extension(...)}                  // Custom extensions
468
)
469
```
470

471
**Usage Examples:**
472

473
```java
474
// API-level external docs
475
@OpenAPIDefinition(
476
    info = @Info(title = "API", version = "1.0"),
477
    externalDocs = @ExternalDocumentation(
478
        description = "Complete API Documentation and Tutorials",
479
        url = "https://docs.example.com/api/v1"
480
    )
481
)
482

483
// Operation-specific external docs
484
@Operation(
485
    summary = "Complex data processing",
486
    externalDocs = @ExternalDocumentation(
487
        description = "Data Processing Algorithm Details",
488
        url = "https://docs.example.com/algorithms/data-processing"
489
    )
490
)
491

492
// Tag external docs
493
@Tag(
494
    name = "advanced",
495
    description = "Advanced operations requiring special configuration",
496
    externalDocs = @ExternalDocumentation(
497
        description = "Advanced Features Configuration Guide",
498
        url = "https://docs.example.com/advanced-config",
499
        extensions = @Extension(
500
            name = "x-doc-type",
501
            properties = @ExtensionProperty(name = "type", value = "tutorial")
502
        )
503
    )
504
)
505

506
// Schema external docs  
507
@Schema(
508
    description = "Complex data structure",
509
    externalDocs = @ExternalDocumentation(
510
        description = "Data Structure Specification",
511
        url = "https://specs.example.com/data-structures/v2"
512
    )
513
)
514
```
515

516
## Configuration Patterns
517

518
### Multi-Environment Setup
519

520
```java
521
@OpenAPIDefinition(
522
    info = @Info(
523
        title = "Multi-Environment API",
524
        version = "1.0.0",
525
        description = "API available across multiple environments"
526
    ),
527
    servers = {
528
        @Server(
529
            url = "https://api.{environment}.{region}.example.com",
530
            description = "Regional servers across environments",
531
            variables = {
532
                @ServerVariable(
533
                    name = "environment",
534
                    defaultValue = "prod",
535
                    allowableValues = {"dev", "staging", "prod"},
536
                    description = "Deployment environment"
537
                ),
538
                @ServerVariable(
539
                    name = "region",
540
                    defaultValue = "us-east",
541
                    allowableValues = {"us-east", "us-west", "eu-central", "ap-southeast"},
542
                    description = "Geographic region"
543
                )
544
            }
545
        ),
546
        @Server(
547
            url = "http://localhost:{port}",
548
            description = "Local development",
549
            variables = @ServerVariable(
550
                name = "port",
551
                defaultValue = "8080",
552
                description = "Local port number"
553
            )
554
        )
555
    }
556
)
557
```
558

559
### Complete API Metadata
560

561
```java
562
@OpenAPIDefinition(
563
    info = @Info(
564
        title = "Enterprise Resource Management API",
565
        version = "3.2.1",
566
        summary = "Comprehensive ERM system API",
567
        description = """
568
            Enterprise Resource Management API providing comprehensive functionality for:
569
            
570
            - **User Management**: Account creation, authentication, role management
571
            - **Resource Management**: Asset tracking, allocation, reporting
572
            - **Financial Operations**: Budgeting, expense tracking, financial reporting
573
            - **Analytics**: Real-time dashboards, custom reports, data export
574
            
575
            This API follows RESTful principles and supports JSON and XML formats.
576
            All endpoints require authentication via JWT tokens or API keys.
577
            """,
578
        termsOfService = "https://example.com/api/terms",
579
        contact = @Contact(
580
            name = "Enterprise API Support",
581
            email = "enterprise-api@example.com",
582
            url = "https://support.example.com/enterprise-api"
583
        ),
584
        license = @License(
585
            name = "Enterprise License Agreement",
586
            url = "https://example.com/licenses/enterprise",
587
            identifier = "Enterprise-1.0"
588
        ),
589
        extensions = {
590
            @Extension(
591
                name = "x-api-metadata",
592
                properties = {
593
                    @ExtensionProperty(name = "category", value = "enterprise"),
594
                    @ExtensionProperty(name = "maturity", value = "stable"),
595
                    @ExtensionProperty(name = "sla", value = "99.9%"),
596
                    @ExtensionProperty(name = "support-tier", value = "premium")
597
                }
598
            )
599
        }
600
    ),
601
    servers = {
602
        @Server(
603
            url = "https://enterprise-api.{region}.example.com",
604
            description = "Enterprise regional servers",
605
            variables = @ServerVariable(
606
                name = "region",
607
                defaultValue = "us",
608
                allowableValues = {"us", "eu", "ap"},
609
                description = "Service region"
610
            )
611
        )
612
    },
613
    tags = {
614
        @Tag(
615
            name = "users",
616
            description = "User account and authentication management",
617
            externalDocs = @ExternalDocumentation(
618
                description = "User Management Guide",
619
                url = "https://docs.example.com/enterprise/users"
620
            )
621
        ),
622
        @Tag(
623
            name = "resources",
624
            description = "Resource allocation and tracking",
625
            externalDocs = @ExternalDocumentation(
626
                description = "Resource Management Guide",
627
                url = "https://docs.example.com/enterprise/resources"
628
            )
629
        ),
630
        @Tag(
631
            name = "analytics",
632
            description = "Reporting and analytics endpoints",
633
            extensions = @Extension(
634
                name = "x-feature-flag",
635
                properties = @ExtensionProperty(name = "requires-premium", value = "true")
636
            )
637
        )
638
    },
639
    externalDocs = @ExternalDocumentation(
640
        description = "Complete Enterprise API Documentation",
641
        url = "https://docs.example.com/enterprise-api"
642
    )
643
)
644
```
645

646
### Versioned API Configuration
647

648
```java
649
@OpenAPIDefinition(
650
    info = @Info(
651
        title = "Versioned API",
652
        version = "2.0.0",
653
        description = "API with version-specific servers and features"
654
    ),
655
    servers = {
656
        @Server(
657
            url = "https://api.example.com/v{version}",
658
            description = "Versioned API endpoint",
659
            variables = @ServerVariable(
660
                name = "version", 
661
                defaultValue = "2",
662
                allowableValues = {"1", "2"},
663
                description = "API version"
664
            )
665
        ),
666
        @Server(
667
            url = "https://v{version}.api.example.com",
668
            description = "Version-specific subdomain",
669
            variables = @ServerVariable(
670
                name = "version",
671
                defaultValue = "2",
672
                allowableValues = {"1", "2"}
673
            )
674
        )
675
    }
676
)
677
```