0
# Documentation Generation
1

2
Core functionality that converts Springfox documentation models into Swagger 2 specification format. Provides comprehensive mapping capabilities for API operations, models, security schemes, and metadata.
3

4
## Capabilities
5

6
### ServiceModelToSwagger2Mapper
7

8
The main mapper that converts Springfox Documentation objects to Swagger 2 model objects using MapStruct for type-safe mapping.
9

10
```java { .api }
11
/**
12
 * Abstract mapper class that converts Springfox documentation to Swagger 2 format
13
 * Uses MapStruct for type-safe object mapping
14
 */
15
@Mapper(uses = {
16
    ModelMapper.class,
17
    ParameterMapper.class,
18
    SecurityMapper.class,
19
    LicenseMapper.class,
20
    VendorExtensionsMapper.class
21
})
22
public abstract class ServiceModelToSwagger2Mapper {
23
    
24
    /**
25
     * Maps Springfox Documentation to Swagger 2 Swagger object
26
     * @param from Springfox Documentation containing API information
27
     * @return Swagger 2 specification object
28
     */
29
    public abstract Swagger mapDocumentation(Documentation from);
30
    
31
    /**
32
     * Maps API info metadata to Swagger 2 Info object
33
     * @param from Springfox ApiInfo containing metadata
34
     * @return Swagger 2 Info object
35
     */
36
    protected abstract Info mapApiInfo(ApiInfo from);
37
    
38
    /**
39
     * Maps contact information
40
     * @param from Springfox Contact object
41
     * @return Swagger 2 Contact object
42
     */
43
    protected abstract Contact map(springfox.documentation.service.Contact from);
44
    
45
    /**
46
     * Maps API operations to Swagger 2 Operation objects
47
     * @param from Springfox Operation containing method details
48
     * @return Swagger 2 Operation object
49
     */
50
    protected abstract Operation mapOperation(springfox.documentation.service.Operation from);
51
    
52
    /**
53
     * Maps API tags for grouping operations
54
     * @param from Springfox Tag object
55
     * @return Swagger 2 Tag object
56
     */
57
    protected abstract Tag mapTag(springfox.documentation.service.Tag from);
58
}
59
```
60

61
**Usage Example:**
62
```java
63
// Typically used internally by the framework
64
ServiceModelToSwagger2Mapper mapper = // injected by Spring
65
Documentation documentation = documentationCache.documentationByGroup("default");
66
Swagger swagger = mapper.mapDocumentation(documentation);
67
```
68

69
### SecurityMapper
70

71
Maps security schemes and authorization configurations to Swagger 2 format.
72

73
```java { .api }
74
/**
75
 * Mapper for security schemes and configurations
76
 */
77
@Mapper
78
public class SecurityMapper {
79
    
80
    /**
81
     * Converts resource listing security schemes to Swagger 2 format
82
     * @param from ResourceListing containing security configuration
83
     * @return Map of security scheme definitions
84
     */
85
    public Map<String, SecuritySchemeDefinition> toSecuritySchemeDefinitions(ResourceListing from);
86
}
87
```
88

89
### ModelMapper
90

91
Maps data model definitions and properties to Swagger 2 format, handling type conversions and property mappings.
92

93
```java { .api }
94
/**
95
 * Mapper for data models and properties
96
 */
97
@Mapper
98
public class ModelMapper {
99
    
100
    /**
101
     * Maps Springfox models to Swagger 2 model definitions
102
     * Handles type conversions, property mappings, and inheritance
103
     */
104
    // Various model mapping methods for different Springfox model types
105
}
106
```
107

108
### ParameterMapper
109

110
Maps API operation parameters to Swagger 2 parameter format.
111

112
```java { .api }
113
/**
114
 * Mapper for operation parameters
115
 */
116
@Mapper
117
public class ParameterMapper {
118
    
119
    /**
120
     * Maps Springfox parameters to Swagger 2 parameter objects
121
     * Handles query parameters, path parameters, headers, etc.
122
     */
123
    // Parameter mapping methods
124
}
125
```
126

127
### Security Scheme Factories
128

129
Factory interfaces and implementations for creating different types of security schemes.
130

131
```java { .api }
132
/**
133
 * Factory interface for creating security scheme definitions
134
 */
135
public interface SecuritySchemeFactory {
136
    /**
137
     * Creates a security scheme definition from Springfox security scheme
138
     * @param securityScheme Springfox security scheme
139
     * @return Swagger 2 security scheme definition
140
     */
141
    SecuritySchemeDefinition create(SecurityScheme securityScheme);
142
}
143

144
/**
145
 * Factory for basic authentication security schemes
146
 */
147
public class BasicAuthFactory implements SecuritySchemeFactory {
148
    public SecuritySchemeDefinition create(SecurityScheme securityScheme);
149
}
150

151
/**
152
 * Factory for OAuth 2 security schemes
153
 */
154
public class OAuth2AuthFactory implements SecuritySchemeFactory {
155
    public SecuritySchemeDefinition create(SecurityScheme securityScheme);
156
}
157

158
/**
159
 * Factory for API key security schemes
160
 */
161
public class ApiKeyAuthFactory implements SecuritySchemeFactory {
162
    public SecuritySchemeDefinition create(SecurityScheme securityScheme);
163
}
164
```
165

166
### Vendor Extensions and Examples
167

168
Mappers for handling vendor extensions and example values in API documentation.
169

170
```java { .api }
171
/**
172
 * Mapper for vendor extensions
173
 */
174
public class VendorExtensionsMapper {
175
    /**
176
     * Maps vendor extension data to Swagger 2 format
177
     * @param extensions Map of extension data
178
     * @return Mapped vendor extensions
179
     */
180
    public Map<String, Object> mapExtensions(Map<String, Object> extensions);
181
}
182

183
/**
184
 * Mapper for example values in API documentation
185
 */
186
public class ExamplesMapper {
187
    /**
188
     * Maps example values to Swagger 2 format
189
     * @param examples Map of example data
190
     * @return Mapped examples
191
     */
192
    public Map<String, Object> mapExamples(Map<String, Object> examples);
193
}
194
```
195

196
### Enum and License Mappers
197

198
Specialized mappers for enumeration values and license information.
199

200
```java { .api }
201
/**
202
 * Mapper for enumeration types
203
 */
204
public class EnumMapper {
205
    /**
206
     * Maps enumeration values to Swagger 2 format
207
     */
208
    // Enum mapping methods
209
}
210

211
/**
212
 * Mapper for license information
213
 */
214
public class LicenseMapper {
215
    /**
216
     * Maps license data to Swagger 2 License objects
217
     */
218
    // License mapping methods
219
}
220
```
221

222
## Mapping Process
223

224
The documentation generation follows this process:
225

226
1. **Documentation Retrieval**: Get Springfox Documentation from DocumentationCache
227
2. **Model Conversion**: Convert Springfox models to Swagger 2 models using specialized mappers
228
3. **Security Mapping**: Transform security schemes using appropriate factories
229
4. **Parameter Processing**: Map operation parameters to Swagger 2 format
230
5. **Response Mapping**: Convert response definitions and examples
231
6. **Metadata Processing**: Map API info, contact, license, and vendor extensions
232
7. **Path Organization**: Organize API operations by paths and HTTP methods
233

234
## Supported Features
235

236
- **Complete API Mapping**: Operations, parameters, responses, and models
237
- **Security Integration**: Basic Auth, OAuth 2, and API Key authentication
238
- **Type Safety**: MapStruct-based mapping with compile-time validation
239
- **Vendor Extensions**: Custom extension support for enhanced documentation
240
- **Example Values**: Rich example support for parameters and responses
241
- **Inheritance Handling**: Model inheritance and composition mapping
242
- **Enum Support**: Enumeration type mapping with allowed values
243
- **License and Contact**: Complete metadata mapping
244

245
## Dependencies
246

247
The mappers depend on:
248
- MapStruct for annotation-based object mapping
249
- Swagger 2 models (io.swagger.models package)
250
- Springfox service models (springfox.documentation.service package)
251
- Jackson for JSON processing capabilities