0
# Parameter Documentation
1

2
Annotations for documenting API parameters, including path parameters, query parameters, form parameters, and request bodies. These annotations provide detailed metadata about parameter types, constraints, and validation rules.
3

4
## Capabilities
5

6
### @ApiParam Annotation
7

8
Adds additional metadata for operation parameters. This annotation can only be used in combination with JAX-RS annotations.
9

10
```java { .api }
11
/**
12
 * Adds additional meta-data for operation parameters
13
 * Can only be used with JAX-RS annotations
14
 * Target: PARAMETER, METHOD, FIELD
15
 * Retention: RUNTIME
16
 */
17
@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
18
@Retention(RetentionPolicy.RUNTIME)
19
@interface ApiParam {
20
    /**
21
     * The parameter name
22
     * Derived from field/method/parameter name if not specified
23
     * Path parameters must always match the path section they represent
24
     */
25
    String name() default "";
26
    
27
    /** Brief description of the parameter */
28
    String value() default "";
29
    
30
    /**
31
     * Describes the default value for the parameter
32
     * JAX-RS @DefaultValue is used if available, can be overridden
33
     */
34
    String defaultValue() default "";
35
    
36
    /**
37
     * Limits acceptable values for this parameter
38
     * Three formats supported:
39
     * 1. List: "first, second, third"
40
     * 2. Range: "range[1, 5]", "range(1, 5)", "range[1, 5)"
41
     * 3. Min/Max: "range[1, infinity]", "range[-infinity, 100]"
42
     */
43
    String allowableValues() default "";
44
    
45
    /**
46
     * Specifies if parameter is required
47
     * Path parameters are always required regardless of this setting
48
     */
49
    boolean required() default false;
50
    
51
    /**
52
     * Allows filtering parameter from API documentation
53
     * See io.swagger.core.filter.SwaggerSpecFilter for details
54
     */
55
    String access() default "";
56
    
57
    /** Specifies whether parameter can accept multiple values */
58
    boolean allowMultiple() default false;
59
    
60
    /** Hides parameter from the list of parameters */
61
    boolean hidden() default false;
62
    
63
    /** Single example for non-body type parameters */
64
    String example() default "";
65
    
66
    /** Examples for the parameter (applies only to BodyParameters) */
67
    Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = ""));
68
    
69
    /** Adds ability to override the detected type */
70
    String type() default "";
71
    
72
    /** Adds ability to provide a custom format */
73
    String format() default "";
74
    
75
    /** Adds ability to set a format as empty */
76
    boolean allowEmptyValue() default false;
77
    
78
    /** Adds ability to be designated as read only */
79
    boolean readOnly() default false;
80
    
81
    /** Adds ability to override collectionFormat with array types */
82
    String collectionFormat() default "";
83
}
84
```
85

86
**Usage Examples:**
87

88
```java
89
// Basic parameter documentation
90
@GET
91
@Path("/users/{id}")
92
public User getUser(
93
    @ApiParam(value = "User ID", required = true)
94
    @PathParam("id") Long id
95
) {
96
    // implementation
97
}
98

99
// Query parameter with constraints
100
@GET
101
@Path("/users")
102
public List<User> searchUsers(
103
    @ApiParam(
104
        value = "Search query", 
105
        example = "john doe"
106
    )
107
    @QueryParam("q") String query,
108
    
109
    @ApiParam(
110
        value = "Results per page",
111
        defaultValue = "10",
112
        allowableValues = "range[1, 100]"
113
    )
114
    @QueryParam("limit") @DefaultValue("10") Integer limit,
115
    
116
    @ApiParam(
117
        value = "User status filter",
118
        allowableValues = "active, inactive, pending"
119
    )
120
    @QueryParam("status") String status
121
) {
122
    // implementation
123
}
124

125
// Form parameter with examples
126
@POST
127
@Path("/users")
128
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
129
public Response createUser(
130
    @ApiParam(value = "User name", required = true, example = "John Doe")
131
    @FormParam("name") String name,
132
    
133
    @ApiParam(value = "Email address", required = true, example = "john@example.com")
134
    @FormParam("email") String email,
135
    
136
    @ApiParam(value = "User age", allowableValues = "range[18, 120]")
137
    @FormParam("age") Integer age
138
) {
139
    // implementation
140
}
141

142
// Body parameter with complex example
143
@PUT
144
@Path("/users/{id}")
145
public Response updateUser(
146
    @ApiParam(value = "User ID", required = true)
147
    @PathParam("id") Long id,
148
    
149
    @ApiParam(
150
        value = "Updated user data",
151
        required = true,
152
        examples = @Example(value = {
153
            @ExampleProperty(
154
                mediaType = "application/json",
155
                value = "{\"name\": \"John Smith\", \"email\": \"john.smith@example.com\"}"
156
            )
157
        })
158
    )
159
    User user
160
) {
161
    // implementation
162
}
163
```
164

165
### @ApiImplicitParam Annotation
166

167
Alternative parameter documentation for non-JAX-RS environments (like Servlets) or when you need to document parameters that aren't explicitly declared in method signatures.
168

169
```java { .api }
170
/**
171
 * Implicitly documents a parameter when it's not explicitly in method signature
172
 * Useful for Servlet environments or framework-managed parameters
173
 * Target: METHOD, TYPE
174
 * Retention: RUNTIME
175
 */
176
@Target({ElementType.METHOD, ElementType.TYPE})
177
@Retention(RetentionPolicy.RUNTIME)
178
@interface ApiImplicitParam {
179
    /** Parameter name */
180
    String name() default "";
181
    
182
    /** Brief description of the parameter */
183
    String value() default "";
184
    
185
    /** Default value for the parameter */
186
    String defaultValue() default "";
187
    
188
    /** Allowable values for the parameter (same format as @ApiParam) */
189
    String allowableValues() default "";
190
    
191
    /** Whether the parameter is required */
192
    boolean required() default false;
193
    
194
    /** 
195
     * Data type of the parameter
196
     * Java class name or primitive type
197
     */
198
    String dataType() default "";
199
    
200
    /** Data type as a class reference */
201
    String dataTypeClass() default "";
202
    
203
    /**
204
     * Parameter type specifying where parameter is located
205
     * Valid values: "query", "header", "path", "formData", "body"
206
     */
207
    String paramType() default "";
208
    
209
    /** Access level for filtering */
210
    String access() default "";
211
    
212
    /** Whether parameter accepts multiple values */
213
    boolean allowMultiple() default false;
214
    
215
    /** Parameter format (e.g., "date", "date-time", "binary") */
216
    String format() default "";
217
    
218
    /** Whether parameter allows empty values */
219
    boolean allowEmptyValue() default false;
220
    
221
    /** Whether parameter is read-only */
222
    boolean readOnly() default false;
223
    
224
    /** Collection format for array parameters */
225
    String collectionFormat() default "";
226
    
227
    /** Example value for the parameter */
228
    String example() default "";
229
}
230
```
231

232
**Usage Examples:**
233

234
```java
235
// Servlet-style parameter documentation
236
@ApiImplicitParam(
237
    name = "userId",
238
    value = "ID of the user to retrieve",
239
    required = true,
240
    dataType = "long",
241
    paramType = "path"
242
)
243
@GET
244
@Path("/users/{userId}")
245
public Response getUserServlet(HttpServletRequest request) {
246
    Long userId = Long.parseLong(request.getPathInfo().split("/")[2]);
247
    // implementation
248
}
249

250
// Header parameter documentation
251
@ApiImplicitParam(
252
    name = "X-API-Version",
253
    value = "API version to use",
254
    dataType = "string",
255
    paramType = "header",
256
    defaultValue = "v1",
257
    allowableValues = "v1, v2"
258
)
259
@GET
260
@Path("/users")
261
public List<User> getUsers(HttpServletRequest request) {
262
    String version = request.getHeader("X-API-Version");
263
    // implementation
264
}
265

266
// Body parameter for complex types
267
@ApiImplicitParam(
268
    name = "user",
269
    value = "User data to create",
270
    required = true,
271
    dataType = "User",
272
    paramType = "body"
273
)
274
@POST
275
@Path("/users")
276
public Response createUserServlet(HttpServletRequest request) {
277
    // Parse JSON from request body
278
    // implementation
279
}
280
```
281

282
### @ApiImplicitParams Annotation
283

284
Container annotation for multiple implicit parameters.
285

286
```java { .api }
287
/**
288
 * Container for multiple @ApiImplicitParam annotations
289
 * Target: METHOD, ANNOTATION_TYPE, TYPE
290
 * Retention: RUNTIME
291
 */
292
@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE, ElementType.TYPE})
293
@Retention(RetentionPolicy.RUNTIME)
294
@interface ApiImplicitParams {
295
    /** Array of implicit parameter definitions */
296
    ApiImplicitParam[] value();
297
}
298
```
299

300
**Usage Examples:**
301

302
```java
303
// Multiple implicit parameters
304
@ApiImplicitParams({
305
    @ApiImplicitParam(
306
        name = "Authorization",
307
        value = "JWT token for authentication",
308
        required = true,
309
        dataType = "string",
310
        paramType = "header"
311
    ),
312
    @ApiImplicitParam(
313
        name = "page",
314
        value = "Page number for pagination",
315
        dataType = "int",
316
        paramType = "query",
317
        defaultValue = "1"
318
    ),
319
    @ApiImplicitParam(
320
        name = "size",
321
        value = "Number of items per page",
322
        dataType = "int", 
323
        paramType = "query",
324
        defaultValue = "20",
325
        allowableValues = "range[1, 100]"
326
    )
327
})
328
@GET
329
@Path("/users")
330
public Response getUsers(HttpServletRequest request) {
331
    // implementation using servlet API
332
}
333

334
// Mixed parameter types
335
@ApiImplicitParams({
336
    @ApiImplicitParam(
337
        name = "file",
338
        value = "File to upload",
339
        required = true,
340
        dataType = "__file",
341
        paramType = "formData"
342
    ),
343
    @ApiImplicitParam(
344
        name = "description", 
345
        value = "File description",
346
        dataType = "string",
347
        paramType = "formData"
348
    ),
349
    @ApiImplicitParam(
350
        name = "Content-Type",
351
        value = "MIME type of the file",
352
        dataType = "string",
353
        paramType = "header",
354
        defaultValue = "application/octet-stream"
355
    )
356
})
357
@POST
358
@Path("/upload")
359
public Response uploadFile(HttpServletRequest request) {
360
    // Handle file upload
361
}
362
```
363

364
### Parameter Type Reference
365

366
Common parameter types and their usage:
367

368
```java
369
// Path parameters - always required
370
@ApiParam(value = "Resource ID", required = true)
371
@PathParam("id") Long id
372

373
// Query parameters - optional by default  
374
@ApiParam(value = "Filter criteria")
375
@QueryParam("filter") String filter
376

377
// Header parameters
378
@ApiParam(value = "API version")
379
@HeaderParam("X-API-Version") String version
380

381
// Form parameters
382
@ApiParam(value = "Form field")
383
@FormParam("field") String field
384

385
// Body parameters (entire request body)
386
@ApiParam(value = "Request payload", required = true)
387
RequestDto request
388
```
389

390
### Validation and Constraints
391

392
```java
393
// Numeric ranges
394
@ApiParam(
395
    value = "Age in years",
396
    allowableValues = "range[0, 150]"
397
)
398
@QueryParam("age") Integer age
399

400
// Enumerated values
401
@ApiParam(
402
    value = "Sort order",
403
    allowableValues = "asc, desc"
404
)
405
@QueryParam("sort") String sort
406

407
// Multiple values
408
@ApiParam(
409
    value = "Category IDs",
410
    allowMultiple = true
411
)
412
@QueryParam("categories") List<Long> categories
413

414
// File upload
415
@ApiParam(
416
    value = "File to upload",
417
    type = "file"
418
)
419
@FormDataParam("file") InputStream fileInputStream
420
```
421

422
### Best Practices
423

424
1. **Use @ApiParam with JAX-RS** - Preferred for JAX-RS applications
425
2. **Use @ApiImplicitParam for Servlets** - When parameters aren't in method signature
426
3. **Always document required parameters** - Set `required = true` for mandatory parameters
427
4. **Provide examples** - Help developers understand expected parameter format
428
5. **Use allowableValues** - Document valid parameter values and ranges
429
6. **Match parameter names** - Ensure names match actual parameter names
430
7. **Document constraints** - Include validation rules and limits
431
8. **Use appropriate paramType** - Specify correct parameter location (query, header, path, etc.)