0
# Core API Documentation
1

2
Core annotations for marking and documenting API resources and operations. These annotations form the foundation of Swagger documentation by identifying which classes and methods should be included in the API specification.
3

4
## Capabilities
5

6
### @Api Annotation
7

8
Marks a class as a Swagger resource and provides API-level metadata. By default, Swagger-Core will only introspect classes annotated with `@Api`.
9

10
```java { .api }
11
/**
12
 * Marks a class as a Swagger resource
13
 * Target: TYPE (classes)
14
 * Retention: RUNTIME
15
 * Inherited: true
16
 */
17
@Target(ElementType.TYPE)
18
@Retention(RetentionPolicy.RUNTIME)
19
@Inherited
20
@interface Api {
21
    /** 
22
     * Implicitly sets a tag for operations (legacy support)
23
     * If tags() is not used, this value sets the tag for operations
24
     * Leading / is removed if present
25
     */
26
    String value() default "";
27
    
28
    /**
29
     * Array of tags for API documentation control
30
     * Used for logical grouping of operations by resources
31
     * Overrides value() if non-empty
32
     */
33
    String[] tags() default "";
34
    
35
    /** @deprecated Not used in 1.5.X, kept for legacy support */
36
    String description() default "";
37
    
38
    /** @deprecated Not used in 1.5.X, kept for legacy support */
39
    String basePath() default "";
40
    
41
    /** @deprecated Not used in 1.5.X, kept for legacy support */
42
    int position() default 0;
43
    
44
    /**
45
     * Corresponds to 'produces' field of operations under this resource
46
     * Comma-separated content types (e.g., "application/json, application/xml")
47
     * Automatically takes JAX-RS @Produces value if present, can override
48
     */
49
    String produces() default "";
50
    
51
    /**
52
     * Corresponds to 'consumes' field of operations under this resource  
53
     * Comma-separated content types for accepted input
54
     * Automatically takes JAX-RS @Consumes value if present, can override
55
     */
56
    String consumes() default "";
57
    
58
    /**
59
     * Sets specific protocols (schemes) for operations under this resource
60
     * Comma-separated values: http, https, ws, wss
61
     */
62
    String protocols() default "";
63
    
64
    /**
65
     * Corresponds to 'security' field of Operation Object
66
     * List of authorizations (security requirements) for operations
67
     * May be overridden by specific operations
68
     */
69
    Authorization[] authorizations() default @Authorization(value = "");
70
    
71
    /** Hides the operations under this resource */
72
    boolean hidden() default false;
73
}
74
```
75

76
**Usage Examples:**
77

78
```java
79
// Basic API marking
80
@Api
81
@Path("/users")
82
public class UserController {
83
    // operations
84
}
85

86
// API with tags and content types
87
@Api(
88
    tags = {"users", "management"}, 
89
    produces = "application/json",
90
    consumes = "application/json"
91
)
92
@Path("/users")
93
public class UserController {
94
    // operations
95
}
96

97
// API with security requirements
98
@Api(
99
    tags = "admin",
100
    authorizations = {
101
        @Authorization(value = "oauth2", scopes = {
102
            @AuthorizationScope(scope = "admin", description = "Admin access")
103
        })
104
    }
105
)
106
@Path("/admin")
107
public class AdminController {
108
    // operations
109
}
110
```
111

112
### @ApiOperation Annotation
113

114
Describes an operation or typically an HTTP method against a specific path. Operations with equivalent paths are grouped in a single Operation Object.
115

116
```java { .api }
117
/**
118
 * Describes an operation or HTTP method against a specific path
119
 * Target: METHOD, TYPE
120
 * Retention: RUNTIME
121
 */
122
@Target({ElementType.METHOD, ElementType.TYPE})
123
@Retention(RetentionPolicy.RUNTIME)
124
@interface ApiOperation {
125
    /**
126
     * Corresponds to 'summary' field of the operation
127
     * Brief description of operation (should be ≤120 characters for Swagger-UI)
128
     * REQUIRED ATTRIBUTE
129
     */
130
    String value();
131
    
132
    /**
133
     * Corresponds to 'notes' field of the operation
134
     * Verbose description of the operation
135
     */
136
    String notes() default "";
137
    
138
    /**
139
     * List of tags for API documentation control
140
     * Used for logical grouping of operations by resources
141
     * Overrides value from @Api#value() or @Api#tags() for this operation
142
     */
143
    String[] tags() default "";
144
    
145
    /**
146
     * Response type of the operation
147
     * In JAX-RS, return type is used automatically unless it's Response
148
     * Setting this property overrides automatically-derived data type
149
     * Primitive class wrappers (Integer, Long) use corresponding primitives
150
     */
151
    Class<?> response() default Void.class;
152
    
153
    /**
154
     * Declares a container wrapping the response
155
     * Valid values: "List", "Set", "Map" (other values ignored)
156
     */
157
    String responseContainer() default "";
158
    
159
    /**
160
     * Specifies reference to response type
161
     * Can be local or remote, used as-is
162
     * Overrides any specified response() class
163
     */
164
    String responseReference() default "";
165
    
166
    /**
167
     * Corresponds to 'method' field as HTTP method used
168
     * For JAX-RS: @GET, @HEAD, @POST, @PUT, @DELETE, @OPTIONS scanned automatically
169
     * @PATCH also supported though not in JAX-RS spec
170
     * For Servlets: must specify HTTP method manually
171
     * Acceptable values: "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS", "PATCH"
172
     */
173
    String httpMethod() default "";
174
    
175
    /** @deprecated Not used in 1.5.X, kept for legacy support */
176
    int position() default 0;
177
    
178
    /**
179
     * Corresponds to 'operationId' field
180
     * Used by third-party tools to uniquely identify operation
181
     * No longer mandatory in Swagger 2.0
182
     */
183
    String nickname() default "";
184
    
185
    /**
186
     * Corresponds to 'produces' field of the operation
187
     * Comma-separated content types this operation generates
188
     * Automatically takes JAX-RS @Produces value, can override
189
     */
190
    String produces() default "";
191
    
192
    /**
193
     * Corresponds to 'consumes' field of the operation
194
     * Comma-separated content types this operation accepts
195
     * Automatically takes JAX-RS @Consumes value, can override  
196
     */
197
    String consumes() default "";
198
    
199
    /**
200
     * Sets specific protocols (schemes) for this operation
201
     * Comma-separated values: http, https, ws, wss
202
     */
203
    String protocols() default "";
204
    
205
    /**
206
     * Corresponds to 'security' field of Operation Object
207
     * List of authorizations (security requirements) for this operation
208
     */
209
    Authorization[] authorizations() default @Authorization(value = "");
210
    
211
    /** Hides the operation from the list of operations */
212
    boolean hidden() default false;
213
    
214
    /**
215
     * List of possible headers provided alongside the response
216
     */
217
    ResponseHeader[] responseHeaders() default @ResponseHeader(name = "", response = Void.class);
218
    
219
    /**
220
     * HTTP status code of the response
221
     * Should be formal HTTP Status Code (see RFC 2616)
222
     */
223
    int code() default 200;
224
    
225
    /** Optional array of extensions */
226
    Extension[] extensions() default @Extension(properties = @ExtensionProperty(name = "", value = ""));
227
    
228
    /** Ignores JsonView annotations while resolving operations and types */
229
    boolean ignoreJsonView() default false;
230
}
231
```
232

233
**Usage Examples:**
234

235
```java
236
// Basic operation
237
@ApiOperation(value = "Get user by ID")
238
@GET
239
@Path("/{id}")
240
public User getUser(@PathParam("id") Long id) {
241
    // implementation
242
}
243

244
// Detailed operation with response info
245
@ApiOperation(
246
    value = "Create new user",
247
    notes = "Creates a new user account with the provided information. Returns the created user with assigned ID.",
248
    response = User.class,
249
    code = 201,
250
    tags = {"users", "creation"}
251
)
252
@POST
253
public Response createUser(User user) {
254
    // implementation
255
}
256

257
// Operation with custom response headers
258
@ApiOperation(
259
    value = "Upload user avatar",
260
    responseHeaders = {
261
        @ResponseHeader(name = "Location", description = "URL of uploaded image", response = String.class),
262
        @ResponseHeader(name = "Content-Length", description = "Size of uploaded file", response = Long.class)
263
    }
264
)
265
@POST
266
@Path("/{id}/avatar")
267
public Response uploadAvatar(@PathParam("id") Long id, InputStream imageData) {
268
    // implementation
269
}
270

271
// Operation with security requirements
272
@ApiOperation(
273
    value = "Delete user account",
274
    notes = "Permanently deletes a user account. This action cannot be undone.",
275
    authorizations = {
276
        @Authorization(value = "oauth2", scopes = {
277
            @AuthorizationScope(scope = "user:delete", description = "Delete user accounts")
278
        })
279
    }
280
)
281
@DELETE
282
@Path("/{id}")
283
public Response deleteUser(@PathParam("id") Long id) {
284
    // implementation
285
}
286

287
// Operation with collection response
288
@ApiOperation(
289
    value = "List all users",
290
    response = User.class,
291
    responseContainer = "List"
292
)
293
@GET
294
public List<User> getAllUsers() {
295
    // implementation
296
}
297
```
298

299
### JAX-RS Integration
300

301
The core annotations are designed to work seamlessly with JAX-RS:
302

303
```java
304
@Api(tags = "products", produces = "application/json")
305
@Path("/products")
306
@Produces(MediaType.APPLICATION_JSON) // Swagger automatically detects this
307
@Consumes(MediaType.APPLICATION_JSON)
308
public class ProductController {
309

310
    @ApiOperation(value = "Search products")
311
    @GET // Swagger automatically detects HTTP method
312
    public List<Product> searchProducts(
313
        @QueryParam("q") String query,
314
        @QueryParam("category") String category
315
    ) {
316
        // JAX-RS annotations work alongside Swagger annotations
317
    }
318
    
319
    @ApiOperation(
320
        value = "Get product details", 
321
        response = Product.class
322
    )
323
    @GET
324
    @Path("/{id}")
325
    public Product getProduct(@PathParam("id") Long id) {
326
        // Path parameters automatically detected
327
    }
328
}
329
```
330

331
### Best Practices
332

333
1. **Always use @Api on resource classes** - Required for Swagger introspection
334
2. **Keep operation summaries concise** - Maximum 120 characters for good Swagger-UI display
335
3. **Use tags consistently** - Group related operations with consistent tag names
336
4. **Specify response types** - Helps with code generation and documentation clarity
337
5. **Include response codes** - Document expected HTTP status codes
338
6. **Use notes for complex operations** - Provide detailed explanations when needed
339
7. **Leverage JAX-RS integration** - Let Swagger auto-detect HTTP methods and content types when possible