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