0
# Documentation Metadata
1

2
Annotations for providing high-level API documentation metadata, external references, and configuration. These annotations define the overall structure and description of the API specification, including contact information, licensing, and external documentation links.
3

4
## Capabilities
5

6
### @Tag Annotation
7

8
Defines API tags for logical grouping of operations. Tags are used to organize operations in the Swagger-UI and provide metadata about groups of related endpoints.
9

10
```java { .api }
11
/**
12
 * Defines API tags for operation grouping
13
 * Target: ANNOTATION_TYPE
14
 * Retention: RUNTIME
15
 */
16
@Target(ElementType.ANNOTATION_TYPE)
17
@Retention(RetentionPolicy.RUNTIME)
18
@interface Tag {
19
    /**
20
     * Name of the tag
21
     * Used as the identifier for grouping operations
22
     * REQUIRED ATTRIBUTE
23
     */
24
    String name();
25
    
26
    /**
27
     * Short description for the tag
28
     * Displayed in Swagger-UI alongside the tag name
29
     */
30
    String description() default "";
31
    
32
    /**
33
     * Additional external documentation for this tag
34
     */
35
    ExternalDocs externalDocs() default @ExternalDocs(url = "");
36
    
37
    /** Optional array of extensions */
38
    Extension[] extensions() default @Extension(properties = @ExtensionProperty(name = "", value = ""));
39
}
40
```
41

42
**Usage Examples:**
43

44
```java
45
// Basic tag definition
46
@SwaggerDefinition(
47
    tags = {
48
        @Tag(name = "users"),
49
        @Tag(name = "products")
50
    }
51
)
52
public class ApiConfiguration {
53
}
54

55
// Tag with description and external docs
56
@SwaggerDefinition(
57
    tags = {
58
        @Tag(
59
            name = "authentication", 
60
            description = "Operations related to user authentication and authorization",
61
            externalDocs = @ExternalDocs(
62
                value = "Authentication Guide",
63
                url = "https://docs.example.com/auth"
64
            )
65
        )
66
    }
67
)
68
public class ApiConfiguration {
69
}
70

71
// Multiple detailed tags
72
@SwaggerDefinition(
73
    tags = {
74
        @Tag(
75
            name = "users",
76
            description = "User management operations",
77
            externalDocs = @ExternalDocs(
78
                value = "User Management Documentation",
79
                url = "https://docs.example.com/users"
80
            )
81
        ),
82
        @Tag(
83
            name = "orders",
84
            description = "Order processing and management",
85
            externalDocs = @ExternalDocs(
86
                value = "Order Processing Guide",
87
                url = "https://docs.example.com/orders"
88
            )
89
        )
90
    }
91
)
92
public class ECommerceApiConfiguration {
93
}
94
```
95

96
### @ExternalDocs Annotation
97

98
References external documentation for operations, parameters, or the API itself. Provides a way to link to additional documentation outside of the Swagger specification.
99

100
```java { .api }
101
/**
102
 * References external documentation
103
 * Target: PARAMETER, METHOD, FIELD
104
 * Retention: RUNTIME
105
 */
106
@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
107
@Retention(RetentionPolicy.RUNTIME)
108
@interface ExternalDocs {
109
    /**
110
     * Description of the external documentation
111
     * Brief explanation of what the external resource contains
112
     */
113
    String value() default "";
114
    
115
    /**
116
     * URL of the external documentation
117
     * Must be a valid URL pointing to the documentation resource
118
     * REQUIRED ATTRIBUTE
119
     */
120
    String url();
121
}
122
```
123

124
**Usage Examples:**
125

126
```java
127
// External docs on API operation
128
@ApiOperation(
129
    value = "Complex calculation endpoint",
130
    notes = "Performs advanced mathematical calculations"
131
)
132
@ExternalDocs(
133
    value = "Mathematical Formula Reference",
134
    url = "https://docs.example.com/math-formulas"
135
)
136
@POST
137
@Path("/calculate")
138
public CalculationResult performCalculation(CalculationInput input) {
139
    // implementation
140
}
141

142
// External docs on model field
143
public class PaymentRequest {
144
    @ApiModelProperty(value = "Credit card number")
145
    @ExternalDocs(
146
        value = "PCI Compliance Guidelines",
147
        url = "https://www.pcisecuritystandards.org/"
148
    )
149
    private String cardNumber;
150
    
151
    @ApiModelProperty(value = "CVV security code")
152
    @ExternalDocs(
153
        value = "CVV Security Information",
154
        url = "https://docs.example.com/security/cvv"
155
    )
156
    private String cvv;
157
}
158

159
// External docs on parameter
160
@ApiOperation(value = "Search products")
161
@GET
162
@Path("/search")
163
public List<Product> searchProducts(
164
    @ApiParam(value = "Search query string")
165
    @ExternalDocs(
166
        value = "Search Syntax Documentation", 
167
        url = "https://docs.example.com/search-syntax"
168
    )
169
    @QueryParam("q") String query
170
) {
171
    // implementation
172
}
173
```
174

175
### @SwaggerDefinition Annotation
176

177
Configures definition-level metadata for the entire Swagger specification. This annotation is used to define global settings that apply to the entire API, including host, base path, security definitions, and API metadata.
178

179
```java { .api }
180
/**
181
 * Configures definition-level metadata for Swagger specification
182
 * Target: TYPE
183
 * Retention: RUNTIME
184
 */
185
@Target(ElementType.TYPE)
186
@Retention(RetentionPolicy.RUNTIME)
187
@interface SwaggerDefinition {
188
    /**
189
     * Host (name or IP) serving the API
190
     * Excludes scheme, port, and path
191
     * May include port number (e.g., "example.com:8080")
192
     */
193
    String host() default "";
194
    
195
    /**
196
     * Base path on which the API is served
197
     * Relative to the host, must start with "/"
198
     */
199
    String basePath() default "";
200
    
201
    /**
202
     * List of MIME types the APIs can consume
203
     * Global default for all operations
204
     * Can be overridden by individual operations
205
     */
206
    String[] consumes() default "";
207
    
208
    /**
209
     * List of MIME types the APIs can produce  
210
     * Global default for all operations
211
     * Can be overridden by individual operations
212
     */
213
    String[] produces() default "";
214
    
215
    /**
216
     * Transfer protocol for the API
217
     * Options: HTTP, HTTPS, WS, WSS, or DEFAULT
218
     */
219
    Scheme[] schemes() default Scheme.DEFAULT;
220
    
221
    /**
222
     * List of tags used by the specification
223
     * Provides metadata about the groups of operations
224
     */
225
    Tag[] tags() default @Tag(name = "");
226
    
227
    /**
228
     * Security scheme definitions available for use
229
     */
230
    SecurityDefinition securityDefinition() default @SecurityDefinition();
231
    
232
    /**
233
     * General information about the API
234
     * Includes title, version, description, contact, and license
235
     */
236
    Info info() default @Info(title = "", version = "");
237
    
238
    /**
239
     * Additional external documentation for this API
240
     */
241
    ExternalDocs externalDocs() default @ExternalDocs(url = "");
242
}
243
```
244

245
**Usage Examples:**
246

247
```java
248
// Basic API configuration
249
@SwaggerDefinition(
250
    info = @Info(
251
        title = "E-Commerce API",
252
        version = "1.0.0"
253
    ),
254
    host = "api.example.com",
255
    basePath = "/v1"
256
)
257
public class ApiConfiguration {
258
}
259

260
// Comprehensive API configuration
261
@SwaggerDefinition(
262
    info = @Info(
263
        title = "E-Commerce Platform API",
264
        version = "2.1.0",
265
        description = "RESTful API for managing products, orders, and customers",
266
        contact = @Contact(
267
            name = "API Support Team",
268
            email = "api-support@example.com",
269
            url = "https://support.example.com"
270
        ),
271
        license = @License(
272
            name = "MIT License",
273
            url = "https://opensource.org/licenses/MIT"
274
        )
275
    ),
276
    host = "api.example.com",
277
    basePath = "/v2",
278
    schemes = {Scheme.HTTPS},
279
    consumes = {"application/json", "application/xml"},
280
    produces = {"application/json", "application/xml"},
281
    tags = {
282
        @Tag(name = "products", description = "Product catalog management"),
283
        @Tag(name = "orders", description = "Order processing"),
284
        @Tag(name = "customers", description = "Customer management"),
285
        @Tag(name = "authentication", description = "Authentication and authorization")
286
    },
287
    securityDefinition = @SecurityDefinition(
288
        apiKeyAuthDefinitions = {
289
            @ApiKeyAuthDefinition(
290
                key = "api_key",
291
                name = "X-API-Key",
292
                in = ApiKeyLocation.HEADER,
293
                description = "API key for authentication"
294
            )
295
        },
296
        oAuth2Definitions = {
297
            @OAuth2Definition(
298
                key = "oauth2",
299
                flow = Flow.ACCESS_CODE,
300
                authorizationUrl = "https://auth.example.com/oauth/authorize",
301
                tokenUrl = "https://auth.example.com/oauth/token",
302
                scopes = {
303
                    @Scope(name = "read", description = "Read access to resources"),
304
                    @Scope(name = "write", description = "Write access to resources"),
305
                    @Scope(name = "admin", description = "Administrative access")
306
                }
307
            )
308
        }
309
    ),
310
    externalDocs = @ExternalDocs(
311
        value = "Full API Documentation",
312
        url = "https://docs.example.com/api"
313
    )
314
)
315
public class ECommerceApiConfiguration {
316
}
317

318
// Development vs Production configuration
319
@SwaggerDefinition(
320
    info = @Info(
321
        title = "Development API",
322
        version = "1.0.0-SNAPSHOT",
323
        description = "Development version of the API - not for production use"
324
    ),
325
    host = "localhost:8080",
326
    basePath = "/api",
327
    schemes = {Scheme.HTTP}
328
)
329
public class DevApiConfiguration {
330
}
331
```
332

333
### @Info Annotation
334

335
Provides high-level metadata about the API including title, version, description, and contact information. This annotation is used within @SwaggerDefinition to define the API's basic information.
336

337
```java { .api }
338
/**
339
 * Provides high-level API metadata
340
 * Target: ANNOTATION_TYPE
341
 * Retention: RUNTIME
342
 */
343
@Target(ElementType.ANNOTATION_TYPE)
344
@Retention(RetentionPolicy.RUNTIME)
345
@interface Info {
346
    /**
347
     * Title of the application
348
     * Used as the main heading in Swagger-UI
349
     * REQUIRED ATTRIBUTE
350
     */
351
    String title();
352
    
353
    /**
354
     * Version of the OpenAPI document
355
     * Distinct from API implementation version
356
     * REQUIRED ATTRIBUTE
357
     */
358
    String version();
359
    
360
    /**
361
     * Short description of the application
362
     * CommonMark syntax can be used for rich text representation
363
     */
364
    String description() default "";
365
    
366
    /**
367
     * URL to the Terms of Service for the API
368
     * Must be in URL format
369
     */
370
    String termsOfService() default "";
371
    
372
    /**
373
     * Contact information for the exposed API
374
     */
375
    Contact contact() default @Contact(name = "");
376
    
377
    /**
378
     * License information for the exposed API
379
     */
380
    License license() default @License(name = "");
381
    
382
    /** Optional array of extensions */
383
    Extension[] extensions() default @Extension(properties = @ExtensionProperty(name = "", value = ""));
384
}
385
```
386

387
**Usage Examples:**
388

389
```java
390
// Basic info
391
@SwaggerDefinition(
392
    info = @Info(
393
        title = "Product Catalog API",
394
        version = "1.0.0"
395
    )
396
)
397

398
// Detailed info with contact and license
399
@SwaggerDefinition(
400
    info = @Info(
401
        title = "E-Commerce Platform API",
402
        version = "2.1.0",
403
        description = "Comprehensive API for managing an e-commerce platform including products, orders, customers, and payments. " +
404
                     "This API follows RESTful principles and provides both JSON and XML response formats.",
405
        termsOfService = "https://example.com/terms",
406
        contact = @Contact(
407
            name = "Platform Engineering Team",
408
            email = "platform-eng@example.com", 
409
            url = "https://example.com/support"
410
        ),
411
        license = @License(
412
            name = "Apache License 2.0",
413
            url = "https://www.apache.org/licenses/LICENSE-2.0"
414
        )
415
    )
416
)
417

418
// Beta version with warnings
419
@SwaggerDefinition(
420
    info = @Info(
421
        title = "Analytics API (Beta)",
422
        version = "0.9.0-beta",
423
        description = "**BETA VERSION**: Advanced analytics and reporting API. " +
424
                     "This API is in beta and may undergo breaking changes. " +
425
                     "Use with caution in production environments.",
426
        contact = @Contact(
427
            name = "Analytics Team",
428
            email = "analytics@example.com"
429
        )
430
    )
431
)
432
```
433

434
### @Contact Annotation
435

436
Defines contact information for the API including name, URL, and email. Used within @Info to provide contact details for API consumers.
437

438
```java { .api }
439
/**
440
 * Defines contact information for API
441
 * Target: ANNOTATION_TYPE
442
 * Retention: RUNTIME
443
 */
444
@Target(ElementType.ANNOTATION_TYPE)
445
@Retention(RetentionPolicy.RUNTIME)
446
@interface Contact {
447
    /**
448
     * Identifying name of the contact person/organization
449
     * REQUIRED ATTRIBUTE
450
     */
451
    String name();
452
    
453
    /**
454
     * URL pointing to the contact information
455
     * Must be in URL format
456
     */
457
    String url() default "";
458
    
459
    /**
460
     * Email address of the contact person/organization
461
     * Must be in email format
462
     */
463
    String email() default "";
464
}
465
```
466

467
**Usage Examples:**
468

469
```java
470
// Contact with all fields
471
@Info(
472
    title = "Customer Service API",
473
    version = "1.0.0",
474
    contact = @Contact(
475
        name = "Customer Service Team",
476
        url = "https://example.com/support",
477
        email = "support@example.com"
478
    )
479
)
480

481
// Contact with name and email only
482
@Info(
483
    title = "Internal Tools API", 
484
    version = "1.2.0",
485
    contact = @Contact(
486
        name = "Internal Tools Team",
487
        email = "internal-tools@company.com"
488
    )
489
)
490

491
// Individual developer contact
492
@Info(
493
    title = "Personal Project API",
494
    version = "0.1.0",
495
    contact = @Contact(
496
        name = "Jane Smith",
497
        url = "https://janesmith.dev",
498
        email = "jane@janesmith.dev"
499
    )
500
)
501
```
502

503
### @License Annotation
504

505
Defines license information for the API including license name and URL. Used within @Info to specify the legal terms under which the API is provided.
506

507
```java { .api }
508
/**
509
 * Defines license information for API
510
 * Target: ANNOTATION_TYPE  
511
 * Retention: RUNTIME
512
 */
513
@Target(ElementType.ANNOTATION_TYPE)
514
@Retention(RetentionPolicy.RUNTIME)
515
@interface License {
516
    /**
517
     * License name used for the API
518
     * REQUIRED ATTRIBUTE
519
     */
520
    String name();
521
    
522
    /**
523
     * URL to the license used for the API
524
     * Must be in URL format
525
     */
526
    String url() default "";
527
}
528
```
529

530
**Usage Examples:**
531

532
```java
533
// Open source licenses
534
@Info(
535
    title = "Open Source API",
536
    version = "1.0.0",
537
    license = @License(
538
        name = "MIT License",
539
        url = "https://opensource.org/licenses/MIT"
540
    )
541
)
542

543
@Info(
544
    title = "Community API",
545
    version = "2.0.0", 
546
    license = @License(
547
        name = "Apache License 2.0",
548
        url = "https://www.apache.org/licenses/LICENSE-2.0"
549
    )
550
)
551

552
// Commercial license
553
@Info(
554
    title = "Enterprise API",
555
    version = "3.1.0",
556
    license = @License(
557
        name = "Commercial License",
558
        url = "https://example.com/licenses/commercial"
559
    )
560
)
561

562
// License name only
563
@Info(
564
    title = "Proprietary API",
565
    version = "1.0.0",
566
    license = @License(name = "Proprietary")
567
)
568
```
569

570
### Scheme Enum
571

572
Defines the transfer protocols supported by the API. Used within @SwaggerDefinition to specify which protocols (HTTP, HTTPS, WebSocket, etc.) are available.
573

574
```java { .api }
575
/**
576
 * Transfer protocol schemes
577
 */
578
enum Scheme {
579
    /** Default - no specific scheme defined */
580
    DEFAULT,
581
    /** HTTP protocol */
582
    HTTP,  
583
    /** HTTPS protocol */
584
    HTTPS,
585
    /** WebSocket protocol */
586
    WS,
587
    /** Secure WebSocket protocol */ 
588
    WSS
589
}
590
```
591

592
**Usage Examples:**
593

594
```java
595
// HTTPS only (secure)
596
@SwaggerDefinition(
597
    schemes = {Scheme.HTTPS},
598
    host = "secure-api.example.com"
599
)
600

601
// Both HTTP and HTTPS
602
@SwaggerDefinition(
603
    schemes = {Scheme.HTTP, Scheme.HTTPS},
604
    host = "api.example.com"
605
)
606

607
// WebSocket support
608
@SwaggerDefinition(
609
    schemes = {Scheme.HTTPS, Scheme.WSS},
610
    host = "realtime-api.example.com",
611
    info = @Info(
612
        title = "Real-time Streaming API",
613
        version = "1.0.0",
614
        description = "API with both REST endpoints and WebSocket streaming"
615
    )
616
)
617

618
// Development environment (HTTP only)
619
@SwaggerDefinition(
620
    schemes = {Scheme.HTTP},
621
    host = "localhost:8080"
622
)
623
```
624

625
### Integration Example
626

627
Here's a complete example showing how all documentation metadata annotations work together:
628

629
```java
630
@SwaggerDefinition(
631
    info = @Info(
632
        title = "E-Commerce Platform API",
633
        version = "2.1.0",
634
        description = "A comprehensive RESTful API for managing an e-commerce platform. " +
635
                     "Supports product catalog management, order processing, customer management, " +
636
                     "and payment processing with full security and monitoring capabilities.",
637
        termsOfService = "https://ecommerce.example.com/terms",
638
        contact = @Contact(
639
            name = "E-Commerce Platform Team",
640
            url = "https://ecommerce.example.com/support", 
641
            email = "api-support@ecommerce.example.com"
642
        ),
643
        license = @License(
644
            name = "MIT License",
645
            url = "https://opensource.org/licenses/MIT"
646
        ),
647
        extensions = {
648
            @Extension(
649
                name = "x-api-id",
650
                properties = @ExtensionProperty(name = "value", value = "ecommerce-api-v2")
651
            )
652
        }
653
    ),
654
    host = "api.ecommerce.example.com",
655
    basePath = "/v2",
656
    schemes = {Scheme.HTTPS},
657
    consumes = {"application/json", "application/xml"},
658
    produces = {"application/json", "application/xml", "text/csv"},
659
    tags = {
660
        @Tag(
661
            name = "products",
662
            description = "Product catalog management operations",
663
            externalDocs = @ExternalDocs(
664
                value = "Product Management Guide",
665
                url = "https://docs.ecommerce.example.com/products"
666
            )
667
        ),
668
        @Tag(
669
            name = "orders", 
670
            description = "Order processing and fulfillment operations",
671
            externalDocs = @ExternalDocs(
672
                value = "Order Processing Documentation", 
673
                url = "https://docs.ecommerce.example.com/orders"
674
            )
675
        ),
676
        @Tag(
677
            name = "customers",
678
            description = "Customer account and profile management",
679
            externalDocs = @ExternalDocs(
680
                value = "Customer Management Guide",
681
                url = "https://docs.ecommerce.example.com/customers"
682
            )
683
        )
684
    },
685
    externalDocs = @ExternalDocs(
686
        value = "Complete API Documentation",
687
        url = "https://docs.ecommerce.example.com"
688
    )
689
)
690
public class ECommerceApiConfiguration {
691
    // Configuration class for API documentation
692
}
693
```
694

695
### Best Practices
696

697
1. **Always provide meaningful titles and descriptions** - Help developers understand the purpose and scope of your API
698
2. **Include contact information** - Make it easy for API consumers to get help or report issues  
699
3. **Specify appropriate licenses** - Clearly communicate legal terms for API usage
700
4. **Use external documentation links** - Provide detailed guides and tutorials outside of the API spec
701
5. **Choose appropriate schemes** - Use HTTPS for production APIs, HTTP only for local development
702
6. **Organize with consistent tags** - Group related operations logically for better navigation
703
7. **Keep descriptions current** - Update API metadata when functionality changes
704
8. **Use semantic versioning** - Follow standard versioning practices for the API version
705
9. **Provide terms of service** - Include legal terms for commercial or public APIs
706
10. **Link to comprehensive documentation** - Use externalDocs to reference complete guides and tutorials