0
# Swagger Annotations Jakarta
1
2
Swagger Annotations Jakarta provides a comprehensive set of Java annotations for defining OpenAPI 3.0 and 3.1 specifications in Jakarta EE environments. The library contains 56 annotation interfaces and 5 enums that enable developers to document REST APIs directly in their source code, supporting all major OpenAPI specification features.
3
4
## Package Information
5
6
- **Package Name**: swagger-annotations-jakarta
7
- **Package Type**: maven
8
- **Group ID**: io.swagger.core.v3
9
- **Artifact ID**: swagger-annotations-jakarta
10
- **Version**: 2.2.31
11
- **Language**: Java
12
- **Installation**: Add to your `pom.xml`:
13
14
```xml
15
<dependency>
16
<groupId>io.swagger.core.v3</groupId>
17
<artifactId>swagger-annotations-jakarta</artifactId>
18
<version>2.2.31</version>
19
</dependency>
20
```
21
22
## Core Imports
23
24
```java
25
import io.swagger.v3.oas.annotations.*;
26
import io.swagger.v3.oas.annotations.info.*;
27
import io.swagger.v3.oas.annotations.media.*;
28
import io.swagger.v3.oas.annotations.parameters.*;
29
import io.swagger.v3.oas.annotations.responses.*;
30
import io.swagger.v3.oas.annotations.security.*;
31
```
32
33
## Basic Usage
34
35
```java
36
import io.swagger.v3.oas.annotations.*;
37
import io.swagger.v3.oas.annotations.info.*;
38
import io.swagger.v3.oas.annotations.media.*;
39
import io.swagger.v3.oas.annotations.parameters.*;
40
import io.swagger.v3.oas.annotations.responses.*;
41
import jakarta.ws.rs.*;
42
43
@OpenAPIDefinition(
44
info = @Info(
45
title = "User API",
46
version = "1.0.0",
47
description = "API for managing user accounts"
48
)
49
)
50
public class UserApplication {}
51
52
@Path("/users")
53
public class UserResource {
54
55
@GET
56
@Operation(
57
summary = "Get user by ID",
58
description = "Retrieves a user account by their unique identifier"
59
)
60
@ApiResponse(
61
responseCode = "200",
62
description = "User found",
63
content = @Content(
64
mediaType = "application/json",
65
schema = @Schema(implementation = User.class)
66
)
67
)
68
@ApiResponse(responseCode = "404", description = "User not found")
69
public Response getUser(
70
@Parameter(description = "User ID", required = true)
71
@PathParam("id") Long id
72
) {
73
// Implementation
74
}
75
76
@POST
77
@Operation(summary = "Create new user")
78
@ApiResponse(responseCode = "201", description = "User created")
79
public Response createUser(
80
@RequestBody(
81
description = "User data",
82
required = true,
83
content = @Content(schema = @Schema(implementation = CreateUserRequest.class))
84
)
85
CreateUserRequest request
86
) {
87
// Implementation
88
}
89
}
90
91
@Schema(description = "User account information")
92
public class User {
93
@Schema(description = "Unique user identifier", example = "123")
94
private Long id;
95
96
@Schema(description = "User's email address", example = "user@example.com")
97
private String email;
98
99
@Schema(description = "User's display name", example = "John Doe")
100
private String name;
101
}
102
```
103
104
## Architecture
105
106
Swagger Annotations Jakarta is built around several key components:
107
108
- **Core Annotations**: Primary annotations for defining operations, parameters, and OpenAPI metadata
109
- **Schema System**: Comprehensive schema definition with validation, typing, and composition features
110
- **Security Framework**: OAuth2, API keys, HTTP authentication, and custom security schemes
111
- **Response Management**: Structured response definitions with content types, headers, and status codes
112
- **Server Configuration**: Multi-environment server definitions with templated variables
113
- **Jakarta EE Compatibility**: Automatic transformation from javax.* to jakarta.* for modern Jakarta EE applications
114
115
## Capabilities
116
117
### Core API Documentation
118
119
Essential annotations for documenting REST operations, parameters, and API structure. These form the foundation of OpenAPI documentation.
120
121
```java { .api }
122
@Operation(
123
summary = "Brief operation description",
124
description = "Detailed operation description",
125
operationId = "uniqueOperationId",
126
tags = {"tag1", "tag2"},
127
parameters = {@Parameter(...)},
128
responses = {@ApiResponse(...)},
129
security = {@SecurityRequirement(...)}
130
)
131
132
@Parameter(
133
name = "paramName",
134
in = ParameterIn.QUERY,
135
description = "Parameter description",
136
required = true,
137
schema = @Schema(type = "string")
138
)
139
140
@OpenAPIDefinition(
141
info = @Info(title = "API Title", version = "1.0.0"),
142
servers = {@Server(url = "https://api.example.com")},
143
security = {@SecurityRequirement(...)}
144
)
145
```
146
147
[Core Annotations](./core-annotations.md)
148
149
### Schema and Media Types
150
151
Comprehensive schema definition system supporting OpenAPI 3.0 and 3.1 features including validation, composition, and conditional schemas.
152
153
```java { .api }
154
@Schema(
155
description = "Schema description",
156
implementation = MyClass.class,
157
required = true,
158
example = "example value",
159
pattern = "regex pattern",
160
minimum = "0",
161
maximum = "100"
162
)
163
164
@Content(
165
mediaType = "application/json",
166
schema = @Schema(implementation = ResponseDto.class),
167
examples = {@ExampleObject(...)}
168
)
169
170
@ArraySchema(
171
schema = @Schema(implementation = String.class),
172
minItems = 1,
173
maxItems = 10,
174
uniqueItems = true
175
)
176
```
177
178
[Schema and Media Types](./schema-media.md)
179
180
### Security Configuration
181
182
Complete security scheme definitions supporting OAuth2 flows, API keys, HTTP authentication, and OpenID Connect.
183
184
```java { .api }
185
@SecurityScheme(
186
name = "bearerAuth",
187
type = SecuritySchemeType.HTTP,
188
scheme = "bearer",
189
bearerFormat = "JWT"
190
)
191
192
@SecurityRequirement(
193
name = "bearerAuth",
194
scopes = {"read:users", "write:users"}
195
)
196
197
@OAuthFlows(
198
authorizationCode = @OAuthFlow(
199
authorizationUrl = "https://auth.example.com/oauth/authorize",
200
tokenUrl = "https://auth.example.com/oauth/token",
201
scopes = {@OAuthScope(name = "read", description = "Read access")}
202
)
203
)
204
```
205
206
[Security Configuration](./security.md)
207
208
### Response Definitions
209
210
Structured response documentation with status codes, content types, headers, and linking between operations.
211
212
```java { .api }
213
@ApiResponse(
214
responseCode = "200",
215
description = "Success response",
216
content = {@Content(
217
mediaType = "application/json",
218
schema = @Schema(implementation = ResponseDto.class)
219
)},
220
headers = {@Header(name = "X-Rate-Limit", schema = @Schema(type = "integer"))},
221
links = {@Link(name = "self", operationId = "getUserById")}
222
)
223
224
@RequestBody(
225
description = "Request payload",
226
required = true,
227
content = {@Content(
228
mediaType = "application/json",
229
schema = @Schema(implementation = CreateUserRequest.class)
230
)}
231
)
232
```
233
234
[Response Management](./responses.md)
235
236
### Server and API Information
237
238
Server definitions, API metadata, contact information, and external documentation configuration.
239
240
```java { .api }
241
@Server(
242
url = "https://api.{environment}.example.com",
243
description = "Main API server",
244
variables = {@ServerVariable(
245
name = "environment",
246
defaultValue = "prod",
247
allowableValues = {"dev", "staging", "prod"}
248
)}
249
)
250
251
@Info(
252
title = "User Management API",
253
version = "2.1.0",
254
description = "Complete user management system",
255
contact = @Contact(name = "API Team", email = "api@example.com"),
256
license = @License(name = "MIT", url = "https://opensource.org/licenses/MIT")
257
)
258
259
@Tag(
260
name = "users",
261
description = "User management operations",
262
externalDocs = @ExternalDocumentation(
263
description = "User guide",
264
url = "https://docs.example.com/users"
265
)
266
)
267
```
268
269
[Server and Info Configuration](./server-info.md)
270
271
### Callbacks and Webhooks
272
273
Advanced callback operations for asynchronous API interactions and webhook definitions supporting OpenAPI 3.1 features.
274
275
```java { .api }
276
@Callback(
277
name = "userStatusUpdate",
278
callbackUrlExpression = "{$request.body#/callbackUrl}",
279
operation = @Operation(
280
method = "POST",
281
summary = "User status changed notification"
282
)
283
)
284
285
@Webhook(
286
name = "userCreated",
287
operation = @Operation(summary = "User created webhook")
288
)
289
```
290
291
[Callbacks and Webhooks](./callbacks.md)
292
293
### Links and Operation References
294
295
Define relationships between operations and enable workflow documentation with parameter passing between linked operations.
296
297
```java { .api }
298
@Link(
299
name = "getUserById",
300
operationId = "getUserById",
301
parameters = @LinkParameter(name = "userId", expression = "$response.body#/id")
302
)
303
304
@LinkParameter(
305
name = "userId",
306
expression = "$response.body#/id"
307
)
308
```
309
310
[Links and References](./links.md)
311
312
### Enums and Constants
313
314
Complete reference for all enumeration types used throughout the annotation system including parameter styles, security schemes, and validation options.
315
316
```java { .api }
317
enum ParameterIn { QUERY, PATH, HEADER, COOKIE, DEFAULT }
318
enum ParameterStyle { FORM, SIMPLE, MATRIX, LABEL, SPACEDELIMITED, PIPEDELIMITED, DEEPOBJECT, DEFAULT }
319
enum SecuritySchemeType { APIKEY, HTTP, OAUTH2, OPENIDCONNECT, MUTUALTLS, DEFAULT }
320
enum SecuritySchemeIn { HEADER, QUERY, COOKIE, DEFAULT }
321
enum Explode { TRUE, FALSE, DEFAULT }
322
```
323
324
[Enums Reference](./enums.md)
325
326
## Jakarta EE Transformation
327
328
This library is automatically generated from the original `swagger-annotations` using Eclipse Transformer:
329
330
- **Original**: Uses `javax.*` imports (Java EE)
331
- **Jakarta Version**: Uses `jakarta.*` imports (Jakarta EE)
332
- **API Compatibility**: Identical API surface - same annotations, attributes, and functionality
333
- **Migration Path**: Seamless upgrade from javax-based applications to Jakarta EE
334
335
## Integration Frameworks
336
337
Compatible with major Jakarta EE REST frameworks:
338
339
- **Jakarta REST (JAX-RS)**: Jersey, RESTEasy, Apache CXF
340
- **Spring Boot**: With springdoc-openapi integration
341
- **MicroProfile OpenAPI**: SmallRye, Open Liberty implementations
342
- **Quarkus**: Built-in OpenAPI support
343
- **Helidon**: Native integration with OpenAPI specification generation
344
345
## OpenAPI 3.1 Features
346
347
Extensive support for OpenAPI 3.1 including:
348
349
- **Webhooks**: `@Webhook` and `@Webhooks` annotations
350
- **Dependent Schemas**: `@DependentSchema` and conditional validation
351
- **Pattern Properties**: `@PatternProperty` for regex-based schema matching
352
- **Enhanced Schema**: Additional validation keywords and composition features
353
- **Improved Security**: Extended security scheme options