0
# Swagger Jersey JAX-RS
1

2
Swagger Jersey JAX-RS is a specialized extension for the Swagger Core library that adds support for Jersey's multipart form data parameters in REST API documentation generation. It automatically processes `@FormDataParam` annotations and converts them into appropriate Swagger parameter definitions, enabling comprehensive OpenAPI documentation for file upload endpoints and form-based APIs.
3

4
## Package Information
5

6
- **Package Name**: swagger-jersey-jaxrs
7
- **Package Type**: maven
8
- **Group ID**: io.swagger
9
- **Artifact ID**: swagger-jersey-jaxrs  
10
- **Language**: Java
11
- **Installation**: Add to your Maven `pom.xml`:
12
  ```xml
13
  <dependency>
14
    <groupId>io.swagger</groupId>
15
    <artifactId>swagger-jersey-jaxrs</artifactId>
16
    <version>1.6.15</version>
17
  </dependency>
18
  ```
19

20
## Core Imports
21

22
```java
23
import io.swagger.jersey.SwaggerJerseyJaxrs;
24
import io.swagger.jaxrs.ext.SwaggerExtension;
25
import com.sun.jersey.multipart.FormDataParam;
26
import com.sun.jersey.core.header.FormDataContentDisposition;
27
import com.sun.jersey.multipart.FormDataBodyPart;
28
import io.swagger.annotations.Api;
29
import io.swagger.annotations.ApiOperation;
30
import javax.ws.rs.POST;
31
import javax.ws.rs.Path;
32
import javax.ws.rs.Consumes;
33
import javax.ws.rs.PathParam;
34
import javax.ws.rs.core.MediaType;
35
import javax.ws.rs.core.Response;
36
import java.io.InputStream;
37
import java.util.List;
38
```
39

40
## Basic Usage
41

42
This library works automatically through Java's Service Provider Interface (SPI). Once added to your classpath, it will be automatically discovered and used by the Swagger JAX-RS library to process Jersey multipart form parameters.
43

44
```java
45
// No explicit setup required - the extension is auto-discovered
46
// Your Jersey resource methods with @FormDataParam will be automatically documented
47

48
@POST
49
@Path("/upload")
50
@Consumes(MediaType.MULTIPART_FORM_DATA)
51
@ApiOperation(value = "Upload a file with metadata")
52
public Response uploadFile(
53
    @FormDataParam("file") InputStream fileInputStream,
54
    @FormDataParam("filename") String filename,
55
    @FormDataParam("description") String description
56
) {
57
    // Implementation
58
    return Response.ok().build();
59
}
60
```
61

62
**Generated OpenAPI Documentation:**
63

64
The above endpoint will automatically generate the following Swagger/OpenAPI parameter definitions:
65

66
```yaml
67
parameters:
68
  - name: file
69
    in: formData
70
    type: file
71
    required: false
72
  - name: filename  
73
    in: formData
74
    type: string
75
    required: false
76
  - name: description
77
    in: formData
78
    type: string
79
    required: false
80
```
81

82
**Advanced Example with Mixed Types:**
83

84
```java
85
@POST
86
@Path("/document/{documentName}.json")
87
@Consumes(MediaType.MULTIPART_FORM_DATA)
88
@ApiOperation(value = "Upload document with metadata")
89
public String processDocument(
90
    @PathParam("documentName") String documentName,
91
    @FormDataParam("document") InputStream documentStream,
92
    @FormDataParam("userId") Integer userId,
93
    @FormDataParam("tags") List<String> tags,
94
    @FormDataParam("metadata") FormDataContentDisposition metadata // This will be ignored
95
) {
96
    return "processed";
97
}
98
```
99

100
This generates:
101

102
```yaml
103
parameters:
104
  - name: documentName
105
    in: path
106
    type: string
107
    required: true
108
  - name: document
109
    in: formData  
110
    type: file
111
    required: false
112
  - name: userId
113
    in: formData
114
    type: integer
115
    format: int32
116
    required: false  
117
  - name: tags
118
    in: formData
119
    type: array
120
    items:
121
      type: string
122
    required: false
123
# Note: metadata parameter is automatically excluded
124
```
125

126
## Architecture
127

128
The library extends the Swagger JAX-RS extension mechanism:
129

130
- **SwaggerJerseyJaxrs**: Main extension class that implements `SwaggerExtension` interface
131
- **Service Provider Interface**: Automatically registered via `META-INF/services` configuration
132
- **Parameter Processing**: Specialized handling for `@FormDataParam` annotations
133
- **Type Detection**: Automatic detection of file uploads (InputStream) vs regular form fields
134

135
## Capabilities
136

137
### Parameter Extraction
138

139
Processes Jersey `@FormDataParam` annotations and converts them to Swagger parameter definitions.
140

141
```java { .api }
142
/**
143
 * Extracts parameters from method annotations, specifically handling FormDataParam
144
 * 
145
 * This method is the core of the Jersey multipart form data processing. It examines
146
 * each annotation on a method parameter and if it finds a @FormDataParam annotation,
147
 * it creates the appropriate Swagger Parameter object.
148
 * 
149
 * @param annotations List of annotations to process - typically from a JAX-RS method parameter
150
 * @param type The Java type of the parameter (e.g., InputStream.class, String.class, Integer.class)
151
 * @param typesToSkip Set of types that should be ignored during processing (inherited from parent)
152
 * @param chain Chain of SwaggerExtension processors for delegation to other extensions
153
 * @return List containing a single FormParameter if @FormDataParam found, empty list if type should be ignored, 
154
 *         or delegates to parent class for other annotation types
155
 * @throws IllegalArgumentException if annotation processing fails
156
 */
157
public List<Parameter> extractParameters(
158
    List<Annotation> annotations, 
159
    Type type, 
160
    Set<Type> typesToSkip,
161
    Iterator<SwaggerExtension> chain
162
);
163
```
164

165
**Behavior:**
166
- Detects `@FormDataParam` annotations
167
- Creates `FormParameter` with type "file" for `InputStream` parameters (file uploads)
168
- Creates `FormParameter` with property schema for other types (regular form fields)
169
- Returns empty list if type should be ignored
170
- Delegates to parent class for non-FormDataParam annotations
171

172
### Class Filtering
173

174
Determines which classes should be ignored during parameter processing.
175

176
```java { .api }
177
/**
178
 * Determines if a class should be ignored during parameter extraction
179
 * 
180
 * This method filters out Jersey-specific multipart classes that should not appear
181
 * in the generated Swagger documentation as they are implementation details rather
182
 * than API parameters that clients need to know about.
183
 * 
184
 * @param cls The class to check for filtering - typically a parameter type from a JAX-RS method
185
 * @return true if the class should be ignored (filtered out), false if it should be processed
186
 */
187
protected boolean shouldIgnoreClass(Class<?> cls);
188
```
189

190
**Behavior:**
191
- Returns `true` for `com.sun.jersey.core.header.FormDataContentDisposition`
192
- Returns `true` for `com.sun.jersey.multipart.FormDataBodyPart`
193
- Returns `false` for all other classes
194

195
## Types
196

197
```java { .api }
198
// Main extension class from io.swagger.jersey package
199
class SwaggerJerseyJaxrs extends AbstractSwaggerExtension {
200
    public List<Parameter> extractParameters(List<Annotation> annotations, Type type, Set<Type> typesToSkip, Iterator<SwaggerExtension> chain);
201
    protected boolean shouldIgnoreClass(Class<?> cls);
202
}
203

204
// Parent class from io.swagger.jaxrs.ext package  
205
abstract class AbstractSwaggerExtension implements SwaggerExtension {
206
    public List<Parameter> extractParameters(List<Annotation> annotations, Type type, Set<Type> typesToSkip, Iterator<SwaggerExtension> chain);
207
    protected boolean shouldIgnoreType(Type type, Set<Type> typesToSkip);
208
    protected boolean shouldIgnoreClass(Class<?> cls);
209
}
210

211
// Extension interface from io.swagger.jaxrs.ext package
212
interface SwaggerExtension {
213
    List<Parameter> extractParameters(List<Annotation> annotations, Type type, Set<Type> typesToSkip, Iterator<SwaggerExtension> chain);
214
    boolean shouldIgnoreType(Type type, Set<Type> typesToSkip);
215
}
216

217
// From io.swagger.models.parameters package
218
class FormParameter extends AbstractSerializableParameter<FormParameter> {
219
    FormParameter type(String type);
220
    FormParameter name(String name);
221
    void setProperty(Property property);
222
    FormParameter description(String description);
223
    FormParameter required(boolean required);
224
}
225

226
// From io.swagger.models.parameters package  
227
interface Parameter {
228
    String getName();
229
    void setName(String name);
230
    String getDescription();
231
    void setDescription(String description);
232
    boolean getRequired();
233
    void setRequired(boolean required);
234
}
235

236
// From io.swagger.models.properties package
237
interface Property {
238
    String getType();
239
    String getFormat();
240
    Object getExample();
241
}
242

243
// From com.sun.jersey.multipart package
244
@interface FormDataParam {
245
    String value();
246
}
247

248
// From com.sun.jersey.core.header package (ignored by extension)
249
class FormDataContentDisposition {
250
    String getName();
251
    String getFileName();
252
    long getSize();
253
}
254

255
// From com.sun.jersey.multipart package (ignored by extension)  
256
class FormDataBodyPart {
257
    FormDataContentDisposition getFormDataContentDisposition();
258
    MediaType getMediaType();
259
    <T> T getValueAs(Class<T> clazz);
260
}
261
```
262

263
## Service Registration
264

265
The extension is automatically registered through Java's Service Provider Interface:
266

267
- **Configuration File**: `META-INF/services/io.swagger.jaxrs.ext.SwaggerExtension`
268
- **Implementation Class**: `io.swagger.jersey.SwaggerJerseyJaxrs`
269
- **Auto-Discovery**: No manual configuration required
270

271
## Dependencies
272

273
This library requires the following dependencies to be present:
274

275
- **Swagger Core**: Core Swagger JAX-RS library for extension mechanism
276
- **Jersey Multipart**: Jersey's multipart support for `@FormDataParam` annotation
277
- **Jackson**: For type construction and property conversion
278
- **Java JAX-RS API**: For annotation processing
279

280
## Error Handling
281

282
The library gracefully handles edge cases:
283

284
- **Missing Annotations**: Delegates to parent extension chain for non-FormDataParam annotations
285
- **Type Conversion Failures**: Uses ModelConverters to safely convert types to properties
286
- **Null Values**: Safely handles null property schemas by creating basic FormParameter
287
- **Ignored Types**: Returns empty parameter list for types that should be skipped