0
# JSON Serialization
1

2
Customized Jackson module for proper Swagger 2 JSON serialization with support for vendor extensions, example values, and Swagger-specific formatting requirements.
3

4
## Capabilities
5

6
### Swagger2JacksonModule
7

8
Custom Jackson module that configures JSON serialization for Swagger 2 objects, ensuring proper formatting and compliance with Swagger 2 specification requirements.
9

10
```java { .api }
11
/**
12
 * Jackson module for customizing Swagger 2 JSON serialization
13
 * Extends SimpleModule and implements JacksonModuleRegistrar for Spring integration
14
 */
15
public class Swagger2JacksonModule extends SimpleModule implements JacksonModuleRegistrar {
16
    
17
    /**
18
     * Conditionally registers this module with the provided ObjectMapper
19
     * Only registers if no existing Swagger mix-in is already configured
20
     * Also disables FAIL_ON_EMPTY_BEANS serialization failure
21
     * 
22
     * @param objectMapper The Jackson ObjectMapper to register with
23
     */
24
    public void maybeRegisterModule(ObjectMapper objectMapper);
25
    
26
    /**
27
     * Sets up Jackson serialization mix-ins for Swagger 2 types
28
     * Configures custom serialization behavior for all Swagger model objects
29
     * 
30
     * @param context Jackson module setup context
31
     */
32
    public void setupModule(SetupContext context);
33
}
34
```
35

36
**Usage Example:**
37
```java
38
// Typically configured automatically by Spring Boot
39
ObjectMapper objectMapper = new ObjectMapper();
40
Swagger2JacksonModule module = new Swagger2JacksonModule();
41
module.maybeRegisterModule(objectMapper);
42

43
// Manual registration
44
objectMapper.registerModule(new Swagger2JacksonModule());
45
```
46

47
### Serialization Mix-ins
48

49
The module configures custom serialization behavior for all major Swagger 2 types:
50

51
```java { .api }
52
/**
53
 * Mix-in class that configures common serialization settings for Swagger types
54
 * Applied to: Swagger, Info, License, Scheme, SecurityRequirement, SecuritySchemeDefinition,
55
 * Model, Operation, Path, Parameter, ExternalDocs, Xml, Tag, Contact
56
 */
57
@JsonAutoDetect
58
@JsonInclude(value = JsonInclude.Include.NON_EMPTY)
59
private class CustomizedSwaggerSerializer {
60
}
61

62
/**
63
 * Mix-in class specifically for Response objects
64
 * Ignores the 'responseSchema' property during serialization
65
 */
66
@JsonAutoDetect
67
@JsonInclude(value = JsonInclude.Include.NON_EMPTY)
68
@JsonIgnoreProperties("responseSchema")
69
private class ResponseSerializer {
70
}
71
```
72

73
### Property Example Serialization
74

75
Custom serializer for handling example values in API documentation with proper JSON formatting.
76

77
```java { .api }
78
/**
79
 * Mix-in interface for Property example serialization
80
 * Applies custom serialization logic to example values
81
 */
82
@JsonAutoDetect
83
@JsonInclude(value = JsonInclude.Include.NON_EMPTY)
84
private interface PropertyExampleSerializerMixin {
85
    
86
    /**
87
     * Custom serialization for example values
88
     * Handles string literals, JSON objects, arrays, and primitive values
89
     */
90
    @JsonSerialize(using = PropertyExampleSerializer.class)
91
    Object getExample();
92
}
93

94
/**
95
 * Custom Jackson serializer for property example values
96
 * Handles various data types and JSON formatting requirements
97
 */
98
public static class PropertyExampleSerializer extends StdSerializer<Object> {
99
    
100
    /**
101
     * Serializes example values with proper JSON formatting
102
     * Handles string literals, JSON objects, arrays, and primitive types
103
     * 
104
     * @param value The example value to serialize
105
     * @param gen Jackson JSON generator
106
     * @param provider Serializer provider
107
     */
108
    public void serialize(Object value, JsonGenerator gen, SerializerProvider provider) throws IOException;
109
    
110
    /**
111
     * Determines if a value should be considered empty
112
     * @param value The value to check
113
     * @return true if the value is null or empty string
114
     */
115
    public boolean isEmpty(Object value);
116
}
117
```
118

119
## Serialization Features
120

121
### Non-Empty Value Inclusion
122

123
All Swagger objects are configured with `JsonInclude.Include.NON_EMPTY`, which means:
124
- Null values are not included in JSON output
125
- Empty strings are not included
126
- Empty collections are not included
127
- This produces cleaner, more compact Swagger JSON
128

129
### Auto-Detection Configuration
130

131
The module uses `@JsonAutoDetect` to automatically detect:
132
- Public fields
133
- Public getter methods
134
- Public setter methods (for deserialization)
135

136
### Example Value Handling
137

138
The custom example serializer handles various data types:
139

140
```java
141
// String literals (quoted strings)
142
"example": "hello world"
143

144
// JSON objects 
145
"example": {"key": "value", "number": 42}
146

147
// JSON arrays
148
"example": [1, 2, 3, "item"]
149

150
// Boolean values
151
"example": true
152

153
// Numeric values  
154
"example": 42.5
155

156
// Raw JSON (when input is already valid JSON)
157
"example": {"raw": "json"}
158
```
159

160
### String Literal Processing
161

162
The example serializer intelligently handles string literals:
163

164
```java { .api }
165
/**
166
 * Checks if a string value is a quoted literal
167
 * @param value String to check
168
 * @return true if starts and ends with quotes (single or double)
169
 */
170
boolean isStringLiteral(String value);
171

172
/**
173
 * Checks if a string represents valid JSON (not a plain string)
174
 * Detects objects, arrays, booleans, and numbers
175
 * @param value String to check
176
 * @return true if the string is valid JSON
177
 */
178
boolean isNotJsonString(String value);
179
```
180

181
## Configuration
182

183
### Automatic Registration
184

185
The module is automatically registered when using the provided Spring configuration:
186

187
```java
188
@Configuration
189
@EnableSwagger2WebMvc
190
public class SwaggerConfig {
191
    // Swagger2JacksonModule is automatically configured
192
}
193
```
194

195
### Manual Configuration
196

197
For custom ObjectMapper configuration:
198

199
```java
200
@Configuration
201
public class JacksonConfig {
202
    
203
    @Bean
204
    @Primary
205
    public ObjectMapper objectMapper() {
206
        ObjectMapper mapper = new ObjectMapper();
207
        
208
        // Register Swagger 2 module
209
        Swagger2JacksonModule swagger2Module = new Swagger2JacksonModule();
210
        swagger2Module.maybeRegisterModule(mapper);
211
        
212
        return mapper;
213
    }
214
}
215
```
216

217
### Serialization Settings
218

219
The module automatically configures these Jackson settings:
220
- `SerializationFeature.FAIL_ON_EMPTY_BEANS = false` - Prevents errors on empty objects
221
- Custom mix-ins for all Swagger 2 model types
222
- Special handling for example values and vendor extensions
223

224
## Supported Types
225

226
The module provides custom serialization for these Swagger 2 types:
227

228
### Core Types
229
- `Swagger` - Root Swagger specification object
230
- `Info` - API metadata information
231
- `License` - License information
232
- `Contact` - Contact information
233

234
### Operations and Paths
235
- `Operation` - API operation definitions
236
- `Path` - API path definitions
237
- `Parameter` - Operation parameters
238
- `Response` - Operation responses
239

240
### Models and Properties
241
- `Model` - Data model definitions
242
- `Property` - Model property definitions
243
- `Xml` - XML-specific metadata
244

245
### Security
246
- `SecurityRequirement` - Security requirements
247
- `SecuritySchemeDefinition` - Security scheme definitions
248

249
### Documentation
250
- `Tag` - Operation tags for grouping
251
- `ExternalDocs` - External documentation links
252
- `Scheme` - Supported protocols (HTTP, HTTPS)
253

254
## JSON Output Optimization
255

256
The serialization produces optimized JSON output:
257

258
1. **Compact Format**: No empty or null values
259
2. **Proper Types**: Correct JSON types for all values
260
3. **Valid Examples**: Properly formatted example values
261
4. **Standard Compliance**: Follows Swagger 2.0 specification
262
5. **Readable Output**: Clean, well-formatted JSON structure
263

264
## Integration Points
265

266
The Jackson module integrates with:
267
- Spring Boot auto-configuration
268
- Springfox documentation generation
269
- Swagger UI and other client tools
270
- Custom ObjectMapper configurations
271
- Third-party JSON processing tools