0
# Swagger Annotations
1

2
Swagger Annotations provides a comprehensive set of Java annotations for defining and documenting REST APIs using the OpenAPI/Swagger specification. These annotations allow developers to declaratively describe their API endpoints, data models, parameters, and responses, enabling automatic generation of OpenAPI specification documents for API documentation, client code generation, and interactive API exploration.
3

4
## Package Information
5

6
- **Package Name**: swagger-annotations
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Group ID**: io.swagger
10
- **Artifact ID**: swagger-annotations
11
- **Installation**: `<dependency><groupId>io.swagger</groupId><artifactId>swagger-annotations</artifactId><version>1.6.15</version></dependency>`
12

13
## Core Imports
14

15
```java
16
import io.swagger.annotations.*;
17
```
18

19
For specific annotations:
20

21
```java
22
import io.swagger.annotations.Api;
23
import io.swagger.annotations.ApiOperation;
24
import io.swagger.annotations.ApiParam;
25
import io.swagger.annotations.ApiModel;
26
import io.swagger.annotations.ApiModelProperty;
27
```
28

29
## Basic Usage
30

31
```java
32
import io.swagger.annotations.*;
33

34
@Api(tags = "users", description = "User management operations")
35
@Path("/users")
36
public class UserController {
37

38
    @ApiOperation(
39
        value = "Get user by ID",
40
        notes = "Returns a single user based on the provided ID",
41
        response = User.class
42
    )
43
    @GET
44
    @Path("/{id}")
45
    public Response getUser(
46
        @ApiParam(value = "User ID", required = true, example = "123")
47
        @PathParam("id") Long id
48
    ) {
49
        // implementation
50
    }
51

52
    @ApiOperation(value = "Create new user", response = User.class)
53
    @POST
54
    public Response createUser(
55
        @ApiParam(value = "User data", required = true)
56
        User user
57
    ) {
58
        // implementation
59
    }
60
}
61

62
@ApiModel(description = "User entity")
63
public class User {
64
    @ApiModelProperty(value = "User ID", example = "123", readOnly = true)
65
    private Long id;
66
    
67
    @ApiModelProperty(value = "User name", required = true, example = "John Doe")
68
    private String name;
69
    
70
    @ApiModelProperty(value = "Email address", required = true, example = "john@example.com")
71
    private String email;
72
}
73
```
74

75
## Architecture
76

77
Swagger Annotations is organized around several key annotation categories:
78

79
- **Core API Annotations**: Define API-level and operation-level metadata (`@Api`, `@ApiOperation`)
80
- **Parameter Annotations**: Document API parameters and inputs (`@ApiParam`, `@ApiImplicitParam`)
81
- **Model Annotations**: Describe data models and their properties (`@ApiModel`, `@ApiModelProperty`)
82
- **Response Annotations**: Document API responses and headers (`@ApiResponse`, `@ResponseHeader`)
83
- **Security Annotations**: Define authentication and authorization requirements
84
- **Documentation Annotations**: Provide additional documentation metadata
85
- **Extension System**: Support for custom properties and extensions
86

87
## Capabilities
88

89
### Core API Documentation
90

91
Essential annotations for marking and documenting API resources and operations. These form the foundation of Swagger documentation.
92

93
```java { .api }
94
@Target(ElementType.TYPE)
95
@interface Api {
96
    String value() default "";
97
    String[] tags() default "";
98
    String produces() default "";
99
    String consumes() default "";
100
    String protocols() default "";
101
    Authorization[] authorizations() default @Authorization(value = "");
102
    boolean hidden() default false;
103
}
104

105
@Target({ElementType.METHOD, ElementType.TYPE})
106
@interface ApiOperation {
107
    String value(); // Required - operation summary
108
    String notes() default "";
109
    String[] tags() default "";
110
    Class<?> response() default Void.class;
111
    String responseContainer() default "";
112
    String responseReference() default "";
113
    String httpMethod() default "";  
114
    int position() default 0; // @deprecated
115
    String nickname() default "";
116
    String produces() default "";
117
    String consumes() default "";
118
    String protocols() default "";
119
    Authorization[] authorizations() default @Authorization(value = "");
120
    boolean hidden() default false;
121
    ResponseHeader[] responseHeaders() default @ResponseHeader(name = "", response = Void.class);
122
    int code() default 200;
123
    Extension[] extensions() default @Extension(properties = @ExtensionProperty(name = "", value = ""));
124
    boolean ignoreJsonView() default false;
125
}
126
```
127

128
[Core API Documentation](./core-api.md)
129

130
### Parameter Documentation
131

132
Annotations for documenting API parameters, including path parameters, query parameters, and request bodies.
133

134
```java { .api }
135
@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
136
@interface ApiParam {
137
    String name() default "";
138
    String value() default "";
139
    String defaultValue() default "";
140
    String allowableValues() default "";
141
    boolean required() default false;
142
    String access() default "";
143
    boolean allowMultiple() default false;
144
    boolean hidden() default false;
145
    String example() default "";
146
    Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = ""));
147
    String type() default "";
148
    String format() default "";
149
    boolean allowEmptyValue() default false;
150
    boolean readOnly() default false;
151
    String collectionFormat() default "";
152
}
153

154
@Target({ElementType.METHOD, ElementType.TYPE})
155
@interface ApiImplicitParam {
156
    String name() default "";
157
    String value() default "";
158
    String defaultValue() default "";
159
    String allowableValues() default "";
160
    boolean required() default false;
161
    String dataType() default "";
162
    String dataTypeClass() default "";
163
    String paramType() default "";
164
    String access() default "";
165
    boolean allowMultiple() default false;
166
    String format() default "";
167
    boolean allowEmptyValue() default false;
168
    boolean readOnly() default false;
169
    String collectionFormat() default "";
170
    String example() default "";
171
}
172

173
@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE, ElementType.TYPE})
174
@interface ApiImplicitParams {
175
    ApiImplicitParam[] value();
176
}
177
```
178

179
[Parameter Documentation](./parameters.md)
180

181
### Data Model Documentation
182

183
Annotations for documenting data models, their properties, and relationships.
184

185
```java { .api }
186
@Target({ElementType.TYPE})
187
@interface ApiModel {
188
    String value() default "";
189
    String description() default "";
190
    Class<?> parent() default Void.class;
191
    String discriminator() default "";
192
    Class<?>[] subTypes() default {};
193
    String reference() default "";
194
}
195

196
@Target({ElementType.METHOD, ElementType.FIELD})  
197
@interface ApiModelProperty {
198
    String value() default "";
199
    String name() default "";
200
    String allowableValues() default "";
201
    String access() default "";
202
    String notes() default "";
203
    String dataType() default "";
204
    boolean required() default false;
205
    int position() default 0;
206
    boolean hidden() default false;
207
    String example() default "";
208
    boolean readOnly() default false; // @deprecated
209
    AccessMode accessMode() default AccessMode.AUTO;
210
    String reference() default "";
211
    boolean allowEmptyValue() default false;
212
    Extension[] extensions() default @Extension(properties = @ExtensionProperty(name = "", value = ""));
213
}
214
```
215

216
[Data Model Documentation](./models.md)
217

218
### Response Documentation
219

220
Annotations for documenting API responses, status codes, and response headers.
221

222
```java { .api }
223
@Target({ElementType.METHOD, ElementType.TYPE})
224
@interface ApiResponse {
225
    int code();
226
    String message();
227
    Class<?> response() default Void.class;
228
    String reference() default "";
229
    ResponseHeader[] responseHeaders() default @ResponseHeader(name = "", response = Void.class);
230
    String responseContainer() default "";
231
}
232

233
@Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD, ElementType.TYPE})
234
@interface ApiResponses {
235
    ApiResponse[] value();
236
}
237

238
@Target(ElementType.ANNOTATION_TYPE)
239
@interface ResponseHeader {
240
    String name();
241
    String description() default "";
242
    Class<?> response();
243
    String responseContainer() default "";
244
}
245
```
246

247
[Response Documentation](./responses.md)
248

249
### Security Configuration
250

251
Annotations for defining authentication and authorization requirements for APIs.
252

253
```java { .api }
254
@Target(ElementType.ANNOTATION_TYPE)
255
@interface Authorization {
256
    String value();
257
    AuthorizationScope[] scopes() default @AuthorizationScope(scope = "", description = "");
258
}
259

260
@Target(ElementType.ANNOTATION_TYPE)
261
@interface AuthorizationScope {
262
    String scope();
263
    String description() default "";
264
}
265

266
@Target(ElementType.ANNOTATION_TYPE)
267
@interface SecurityDefinition {
268
    ApiKeyAuthDefinition[] apiKeyAuthDefintions() default @ApiKeyAuthDefinition(key = "", name = "", in = ApiKeyLocation.HEADER);
269
    BasicAuthDefinition[] basicAuthDefinions() default @BasicAuthDefinition(key = "");
270
    OAuth2Definition[] oAuth2Definitions() default @OAuth2Definition(key = "", authorizationUrl = "");
271
}
272
```
273

274
[Security Configuration](./security.md)
275

276
### Documentation Metadata
277

278
Additional annotations for providing documentation metadata and external references.
279

280
```java { .api }
281
@Target({ElementType.TYPE, ElementType.METHOD})
282
@interface Tag {
283
    String name();
284
    String description() default "";
285
    ExternalDocs externalDocs() default @ExternalDocs(value = "", url = "");
286
}
287

288
@Target(ElementType.ANNOTATION_TYPE)
289
@interface ExternalDocs {
290
    String value() default "";
291
    String url();
292
}
293

294
@Target(ElementType.TYPE)
295
@interface SwaggerDefinition {
296
    Info info() default @Info(title = "", version = "");
297
    String host() default "";
298
    String basePath() default "";
299
    Scheme[] schemes() default {};
300
    String[] consumes() default {};
301
    String[] produces() default {};
302
    Tag[] tags() default {};
303
    ExternalDocs externalDocs() default @ExternalDocs(url = "");
304
}
305
```
306

307
[Documentation Metadata](./documentation.md)
308

309
### Extension System
310

311
Annotations for adding custom properties and extensions to the OpenAPI specification.
312

313
```java { .api }
314
@Target(ElementType.ANNOTATION_TYPE)
315
@interface Extension {
316
    String name() default "";
317
    ExtensionProperty[] properties();
318
}
319

320
@Target(ElementType.ANNOTATION_TYPE)
321
@interface ExtensionProperty {
322
    String name();
323
    String value();
324
}
325

326
@Target(ElementType.ANNOTATION_TYPE)
327
@interface Example {
328
    ExampleProperty[] value();
329
}
330

331
@Target(ElementType.ANNOTATION_TYPE)
332
@interface ExampleProperty {
333
    String mediaType() default "";
334
    String value();
335
}
336
```
337

338
[Extension System](./extensions.md)
339

340
## Types
341

342
### ApiKeyAuthDefinition with ApiKeyLocation Enum
343

344
```java { .api }
345
@Target(ElementType.ANNOTATION_TYPE)
346
@interface ApiKeyAuthDefinition {
347
    String key();
348
    String description() default "";
349
    ApiKeyLocation in();
350
    String name();
351
    
352
    enum ApiKeyLocation {
353
        HEADER, QUERY;
354
        
355
        public static ApiKeyLocation forValue(String value);
356
        public String toValue();
357
    }
358
}
359
```
360

361
### OAuth2Definition with Flow Enum
362

363
```java { .api }
364
@Target(ElementType.ANNOTATION_TYPE)
365
@interface OAuth2Definition {
366
    String key();
367
    String description() default "";
368
    Flow flow();
369
    String authorizationUrl() default "";
370
    String tokenUrl() default "";
371
    Scope[] scopes() default {};
372
    
373
    enum Flow {
374
        IMPLICIT, ACCESS_CODE, PASSWORD, APPLICATION
375
    }
376
}
377

378
@Target(ElementType.ANNOTATION_TYPE)
379
@interface Scope {
380
    String name();
381
    String description();
382
}
383
```
384

385
### ApiModelProperty with AccessMode Enum
386

387
```java { .api }
388
// AccessMode is nested within ApiModelProperty
389
enum AccessMode {
390
    AUTO, READ_ONLY, READ_WRITE
391
}
392
```
393

394
### SwaggerDefinition with Scheme Enum
395

396
```java { .api }
397
@Target(ElementType.TYPE)
398
@interface SwaggerDefinition {
399
    String host() default "";
400
    String basePath() default "";
401
    String[] consumes() default {};
402
    String[] produces() default {};
403
    Scheme[] schemes() default Scheme.DEFAULT;
404
    Tag[] tags() default @Tag(name = "");
405
    SecurityDefinition securityDefinition() default @SecurityDefinition();
406
    Info info() default @Info(title = "", version = "");
407
    ExternalDocs externalDocs() default @ExternalDocs(url = "");
408
    
409
    enum Scheme {
410
        DEFAULT, HTTP, HTTPS, WS, WSS
411
    }
412
}
413
```
414

415
### Configuration Types
416

417
```java { .api }
418
@Target(ElementType.ANNOTATION_TYPE)
419
@interface Info {
420
    String title();
421
    String description() default "";
422
    String version();
423
    String termsOfService() default "";
424
    Contact contact() default @Contact(name = "");
425
    License license() default @License(name = "");
426
}
427

428
@Target(ElementType.ANNOTATION_TYPE)
429
@interface Contact {
430
    String name() default "";
431
    String url() default "";
432
    String email() default "";
433
}
434

435
@Target(ElementType.ANNOTATION_TYPE)
436
@interface License {
437
    String name() default "";
438
    String url() default "";
439
}
440
```