0
# Swagger Annotations
1

2
Swagger Core annotations library providing OpenAPI 3.x annotations for Java applications, enabling developers to document REST APIs with metadata annotations.
3

4
## Package Information
5

6
The swagger-annotations library is a Maven artifact that provides comprehensive Java annotations for OpenAPI 3.x specification generation.
7

8
```xml { .api }
9
<dependency>
10
    <groupId>io.swagger.core.v3</groupId>
11
    <artifactId>swagger-annotations</artifactId>
12
    <version>2.2.31</version>
13
</dependency>
14
```
15

16
**Jakarta Namespace Support:**
17
Since version 2.1.7, Swagger Core provides parallel artifacts with the `-jakarta` suffix for Jakarta EE compatibility:
18

19
```xml { .api }
20
<dependency>
21
    <groupId>io.swagger.core.v3</groupId>
22
    <artifactId>swagger-annotations-jakarta</artifactId>
23
    <version>2.2.31</version>
24
</dependency>
25
```
26

27
**Gradle Installation:**
28

29
```gradle { .api }
30
implementation 'io.swagger.core.v3:swagger-annotations:2.2.31'
31

32
// For Jakarta namespace
33
implementation 'io.swagger.core.v3:swagger-annotations-jakarta:2.2.31'
34
```
35

36
**Package Details:**
37
- **Group ID:** `io.swagger.core.v3`
38
- **Artifact ID:** `swagger-annotations` (or `swagger-annotations-jakarta`)
39
- **Version:** `2.2.31`
40
- **License:** Apache License 2.0
41
- **Java Support:** Compatible with both javax and jakarta namespaces
42

43
## Core Imports
44

45
All annotations are located under the `io.swagger.v3.oas.annotations` package hierarchy:
46

47
```java { .api }
48
// Core annotations
49
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
50
import io.swagger.v3.oas.annotations.Operation;
51
import io.swagger.v3.oas.annotations.Parameter;
52
import io.swagger.v3.oas.annotations.Hidden;
53

54
// Schema and media type annotations
55
import io.swagger.v3.oas.annotations.media.Schema;
56
import io.swagger.v3.oas.annotations.media.ArraySchema;
57
import io.swagger.v3.oas.annotations.media.Content;
58

59
// Response annotations
60
import io.swagger.v3.oas.annotations.responses.ApiResponse;
61
import io.swagger.v3.oas.annotations.responses.ApiResponses;
62

63
// Security annotations
64
import io.swagger.v3.oas.annotations.security.SecurityScheme;
65
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
66

67
// Parameter annotations
68
import io.swagger.v3.oas.annotations.parameters.RequestBody;
69

70
// Server and tag annotations
71
import io.swagger.v3.oas.annotations.servers.Server;
72
import io.swagger.v3.oas.annotations.tags.Tag;
73
import io.swagger.v3.oas.annotations.info.Info;
74
```
75

76
## Basic Usage
77

78
### API Definition and Operation Documentation
79

80
Document your REST API endpoints with comprehensive OpenAPI metadata:
81

82
```java { .api }
83
@RestController
84
@OpenAPIDefinition(
85
    info = @Info(
86
        title = "Pet Store API",
87
        version = "1.0.0",
88
        description = "A sample API for managing pets"
89
    ),
90
    tags = {
91
        @Tag(name = "pets", description = "Pet operations")
92
    }
93
)
94
public class PetController {
95
    
96
    @Operation(
97
        summary = "Find pet by ID",
98
        description = "Returns a single pet",
99
        tags = {"pets"}
100
    )
101
    @ApiResponse(
102
        responseCode = "200",
103
        description = "Successful operation",
104
        content = @Content(
105
            mediaType = "application/json",
106
            schema = @Schema(implementation = Pet.class)
107
        )
108
    )
109
    @ApiResponse(
110
        responseCode = "404", 
111
        description = "Pet not found"
112
    )
113
    @GetMapping("/pets/{id}")
114
    public Pet getPetById(
115
        @Parameter(
116
            description = "ID of pet to return",
117
            required = true,
118
            schema = @Schema(type = "integer", format = "int64")
119
        )
120
        @PathVariable Long id
121
    ) {
122
        return petService.findById(id);
123
    }
124
}
125
```
126

127
### Request Body and Schema Documentation
128

129
Define request body schemas and validation constraints:
130

131
```java { .api }
132
@PostMapping("/pets")
133
@Operation(summary = "Add a new pet", tags = {"pets"})
134
@ApiResponse(
135
    responseCode = "201",
136
    description = "Pet created successfully",
137
    content = @Content(schema = @Schema(implementation = Pet.class))
138
)
139
public Pet createPet(
140
    @RequestBody(
141
        description = "Pet object to be added",
142
        required = true,
143
        content = @Content(
144
            mediaType = "application/json",
145
            schema = @Schema(implementation = CreatePetRequest.class)
146
        )
147
    )
148
    @Valid @org.springframework.web.bind.annotation.RequestBody CreatePetRequest request
149
) {
150
    return petService.create(request);
151
}
152

153
@Schema(description = "Pet data model")
154
public class Pet {
155
    @Schema(description = "Pet ID", example = "1", accessMode = Schema.AccessMode.READ_ONLY)
156
    private Long id;
157
    
158
    @Schema(description = "Pet name", example = "Fluffy", required = true, maxLength = 50)
159
    private String name;
160
    
161
    @Schema(description = "Pet category", implementation = Category.class)
162
    private Category category;
163
    
164
    @Schema(description = "Pet status", allowableValues = {"available", "pending", "sold"})
165
    private String status;
166
    
167
    // getters and setters
168
}
169
```
170

171
## Architecture
172

173
The swagger-annotations library provides 56 annotations organized into logical categories:
174

175
### 1. Core API Documentation
176
- **Operation-level annotations** for HTTP methods and endpoint documentation
177
- **Parameter annotations** for request parameters, headers, and path variables
178
- **OpenAPI definition annotations** for API-level metadata
179

180
### 2. Schema and Media Types
181
- **Schema annotations** for data model documentation with validation
182
- **Array schema annotations** for collection types
183
- **Content and media type annotations** for request/response body definitions
184

185
### 3. Response Documentation
186
- **Response annotations** for HTTP response documentation
187
- **Content negotiation** support for multiple media types
188

189
### 4. Security Configuration
190
- **Security scheme annotations** for authentication and authorization
191
- **OAuth2 flow support** with comprehensive configuration options
192
- **Security requirement annotations** for operation-level security
193

194
### 5. Server and Metadata
195
- **Server annotations** for API server configuration
196
- **Tag annotations** for logical operation grouping
197
- **Info annotations** for API metadata (version, contact, license)
198

199
### 6. Advanced Features
200
- **Extension annotations** for vendor-specific OpenAPI extensions
201
- **Callback annotations** for asynchronous operation documentation
202
- **Webhook annotations** for event-driven API documentation
203
- **OpenAPI 3.1 features** including enhanced JSON Schema support
204

205
## Capabilities
206

207
### Core API Documentation
208
Document REST API operations with comprehensive metadata including operation IDs, descriptions, tags, and deprecation status. Handle parameter validation, response definitions, and security requirements at the operation level.
209

210
```java { .api }
211
@Operation(
212
    operationId = "getPetById",
213
    summary = "Find pet by ID",
214
    description = "Returns a single pet based on the provided ID",
215
    tags = {"pets"},
216
    deprecated = false,
217
    security = @SecurityRequirement(name = "api_key"),
218
    responses = {
219
        @ApiResponse(responseCode = "200", description = "Successful operation"),
220
        @ApiResponse(responseCode = "404", description = "Pet not found")
221
    }
222
)
223
```
224

225
[Core Annotations](./core-annotations.md)
226

227
### Schema and Media Type Documentation
228
Define comprehensive data schemas with validation constraints, type information, and example values. Support for complex object hierarchies, arrays, and polymorphic types.
229

230
```java { .api }
231
@Schema(
232
    description = "Pet category information",
233
    required = true,
234
    example = "{ \"id\": 1, \"name\": \"Dogs\" }",
235
    minProperties = 1,
236
    maxProperties = 10
237
)
238
@ArraySchema(
239
    arraySchema = @Schema(description = "List of pets"),
240
    schema = @Schema(implementation = Pet.class),
241
    minItems = 0,
242
    maxItems = 100,
243
    uniqueItems = true
244
)
245
```
246

247
[Schema and Media Types](./schema-media.md)
248

249
### Response Documentation
250
Document API responses with status codes, headers, content types, and schema definitions. Support for multiple response scenarios and content negotiation.
251

252
```java { .api }
253
@ApiResponses({
254
    @ApiResponse(
255
        responseCode = "200",
256
        description = "Successful operation",
257
        headers = @Header(name = "X-Rate-Limit", description = "Request limit"),
258
        content = @Content(
259
            mediaType = "application/json",
260
            schema = @Schema(implementation = Pet.class)
261
        )
262
    ),
263
    @ApiResponse(responseCode = "400", description = "Invalid request")
264
})
265
```
266

267
[Response Documentation](./responses.md)
268

269
### Security Configuration
270
Configure authentication and authorization schemes including API keys, OAuth2, OpenID Connect, and mutual TLS. Define security requirements at API and operation levels.
271

272
```java { .api }
273
@SecurityScheme(
274
    name = "bearerAuth",
275
    type = SecuritySchemeType.HTTP,
276
    scheme = "bearer",
277
    bearerFormat = "JWT",
278
    description = "JWT token authentication"
279
)
280
@SecurityRequirement(name = "bearerAuth", scopes = {"read", "write"})
281
```
282

283
[Security Configuration](./security.md)
284

285
### Server and Tag Management
286
Configure API servers with variable URL templates and define logical groupings of operations with tags and comprehensive metadata.
287

288
```java { .api }
289
@Server(
290
    url = "https://{environment}.petstore.io/v1",
291
    description = "Pet Store API server",
292
    variables = @ServerVariable(
293
        name = "environment",
294
        description = "Server environment",
295
        defaultValue = "api",
296
        allowableValues = {"api", "staging", "dev"}
297
    )
298
)
299
@Tag(name = "pets", description = "Everything about your pets")
300
```
301

302
[Servers and Tags](./servers-tags.md)
303

304
### Advanced Features
305
Leverage OpenAPI extensions, callback definitions for asynchronous operations, webhook documentation, and OpenAPI 3.1 enhanced features including conditional schemas and improved validation.
306

307
```java { .api }
308
@Extension(name = "x-custom-property", properties = {
309
    @ExtensionProperty(name = "feature", value = "enabled"),
310
    @ExtensionProperty(name = "version", value = "1.0")
311
})
312
@Callback(
313
    name = "statusCallback",
314
    callbackUrlExpression = "{$request.body#/callbackUrl}",
315
    operation = @Operation(summary = "Status update callback")
316
)
317
@Webhook(
318
    name = "petUpdated",
319
    operation = @Operation(
320
        summary = "Pet update notification",
321
        requestBody = @RequestBody(
322
            content = @Content(schema = @Schema(implementation = PetUpdateEvent.class))
323
        )
324
    )
325
)
326
```
327

328
[Advanced Features](./advanced-features.md)
329

330
## Integration Patterns
331

332
### Spring Boot Integration
333
The annotations integrate seamlessly with Spring Boot applications and Spring MVC controllers:
334

335
```java { .api }
336
@RestController
337
@RequestMapping("/api/v1")
338
@Tag(name = "user-controller", description = "User management operations")
339
public class UserController {
340
    
341
    @GetMapping("/users")
342
    @Operation(summary = "Get all users", tags = {"users"})
343
    public List<User> getAllUsers(
344
        @Parameter(description = "Page number", example = "0")
345
        @RequestParam(defaultValue = "0") int page,
346
        
347
        @Parameter(description = "Page size", example = "20")
348
        @RequestParam(defaultValue = "20") int size
349
    ) {
350
        return userService.findAll(page, size);
351
    }
352
}
353
```
354

355
### JAX-RS Integration
356
Compatible with JAX-RS applications for comprehensive REST API documentation:
357

358
```java { .api }
359
@Path("/pets")
360
@Tag(name = "pets")
361
public class PetResource {
362
    
363
    @GET
364
    @Path("/{id}")
365
    @Produces(MediaType.APPLICATION_JSON)
366
    @Operation(summary = "Get pet by ID")
367
    public Response getPet(
368
        @Parameter(description = "Pet ID") @PathParam("id") Long id
369
    ) {
370
        Pet pet = petService.findById(id);
371
        return Response.ok(pet).build();
372
    }
373
}
374
```
375

376
### Validation Integration
377
Works with Bean Validation (JSR 303/349/380) annotations for comprehensive validation documentation:
378

379
```java { .api }
380
@Schema(description = "User registration request")
381
public class UserRegistrationRequest {
382
    @NotBlank
383
    @Size(min = 2, max = 50)
384
    @Schema(description = "User's first name", example = "John", minLength = 2, maxLength = 50)
385
    private String firstName;
386
    
387
    @Email
388
    @NotBlank
389
    @Schema(description = "User's email address", format = "email", example = "john@example.com")
390
    private String email;
391
    
392
    @Valid
393
    @Schema(description = "User's address information")
394
    private Address address;
395
}
396
```