0
# Web Integration
1

2
REST endpoints and controllers that serve generated Swagger 2 JSON documentation to clients and Swagger UI applications. Provides both WebMVC and WebFlux controller implementations for different Spring application types.
3

4
## Capabilities
5

6
### Swagger2ControllerWebMvc
7

8
Spring WebMVC controller that serves Swagger 2 JSON documentation via HTTP endpoints in servlet-based applications.
9

10
```java { .api }
11
/**
12
 * Controller for serving Swagger 2 documentation in WebMVC applications
13
 * Handles HTTP requests and returns JSON-formatted Swagger specifications
14
 */
15
@Controller
16
@ConditionalOnClass(name = "javax.servlet.http.HttpServletRequest")
17
@ApiIgnore
18
public class Swagger2ControllerWebMvc {
19
    
20
    /**
21
     * Constructor for WebMVC Swagger controller
22
     * @param environment Spring environment for property resolution
23
     * @param documentationCache Cache for accessing documentation by group
24
     * @param mapper Mapper for converting documentation to Swagger format
25
     * @param jsonSerializer Serializer for converting Swagger objects to JSON
26
     */
27
    public Swagger2ControllerWebMvc(
28
        Environment environment,
29
        DocumentationCache documentationCache,
30
        ServiceModelToSwagger2Mapper mapper,
31
        JsonSerializer jsonSerializer
32
    );
33
    
34
    /**
35
     * GET endpoint that returns Swagger 2 JSON documentation
36
     * Default endpoint: /v2/api-docs
37
     * Configurable via: springfox.documentation.swagger.v2.path
38
     * 
39
     * @param swaggerGroup Optional group name for multi-group documentation (default: "default")
40
     * @param servletRequest HTTP servlet request for host/path resolution
41
     * @return ResponseEntity containing JSON-formatted Swagger specification
42
     */
43
    @RequestMapping(
44
        value = "/v2/api-docs",
45
        method = RequestMethod.GET,
46
        produces = { "application/json", "application/hal+json" }
47
    )
48
    @PropertySourcedMapping(
49
        value = "${springfox.documentation.swagger.v2.path}",
50
        propertyKey = "springfox.documentation.swagger.v2.path"
51
    )
52
    @ResponseBody
53
    public ResponseEntity<Json> getDocumentation(
54
        @RequestParam(value = "group", required = false) String swaggerGroup,
55
        HttpServletRequest servletRequest
56
    );
57
}
58
```
59

60
**Usage Example:**
61
```bash
62
# Get default group documentation
63
curl http://localhost:8080/v2/api-docs
64

65
# Get specific group documentation
66
curl http://localhost:8080/v2/api-docs?group=admin-api
67

68
# Custom endpoint path (if configured)
69
curl http://localhost:8080/api/swagger.json
70
```
71

72
### Swagger2ControllerWebFlux
73

74
Spring WebFlux controller that serves Swagger 2 JSON documentation via HTTP endpoints in reactive applications.
75

76
```java { .api }
77
/**
78
 * Controller for serving Swagger 2 documentation in WebFlux applications
79
 * Handles reactive HTTP requests and returns JSON-formatted Swagger specifications
80
 */
81
@Controller
82
@ConditionalOnClass(name = "org.springframework.web.reactive.BindingContext")
83
@ApiIgnore
84
public class Swagger2ControllerWebFlux {
85
    
86
    /**
87
     * Constructor for WebFlux Swagger controller
88
     * @param documentationCache Cache for accessing documentation by group
89
     * @param mapper Mapper for converting documentation to Swagger format
90
     * @param jsonSerializer Serializer for converting Swagger objects to JSON
91
     */
92
    public Swagger2ControllerWebFlux(
93
        DocumentationCache documentationCache,
94
        ServiceModelToSwagger2Mapper mapper,
95
        JsonSerializer jsonSerializer
96
    );
97
    
98
    /**
99
     * GET endpoint that returns Swagger 2 JSON documentation
100
     * Default endpoint: /v2/api-docs
101
     * Configurable via: springfox.documentation.swagger.v2.path
102
     * 
103
     * @param swaggerGroup Optional group name for multi-group documentation (default: "default")
104
     * @param request Reactive HTTP request for host/path resolution
105
     * @return ResponseEntity containing JSON-formatted Swagger specification
106
     */
107
    @RequestMapping(
108
        value = "/v2/api-docs",
109
        method = RequestMethod.GET,
110
        produces = { "application/json", "application/hal+json" }
111
    )
112
    @PropertySourcedMapping(
113
        value = "${springfox.documentation.swagger.v2.path}",
114
        propertyKey = "springfox.documentation.swagger.v2.path"
115
    )
116
    @ResponseBody
117
    public ResponseEntity<Json> getDocumentation(
118
        @RequestParam(value = "group", required = false) String swaggerGroup,
119
        ServerHttpRequest request
120
    );
121
}
122
```
123

124
**Usage Example:**
125
```bash
126
# Get default group documentation (same as WebMVC)
127
curl http://localhost:8080/v2/api-docs
128

129
# Get specific group documentation
130
curl http://localhost:8080/v2/api-docs?group=admin-api
131
```
132

133
## Endpoint Configuration
134

135
### Default Endpoint
136

137
Both controllers serve documentation at `/v2/api-docs` by default, which is the standard Swagger 2 documentation endpoint expected by Swagger UI and other tools.
138

139
### Custom Endpoint Path
140

141
You can customize the endpoint path using the `springfox.documentation.swagger.v2.path` property:
142

143
```properties
144
# application.properties
145
springfox.documentation.swagger.v2.path=/api/swagger.json
146
```
147

148
### Host Override
149

150
WebMVC controller supports hostname override via the `springfox.documentation.swagger.v2.host` property:
151

152
```properties
153
# application.properties
154
springfox.documentation.swagger.v2.host=api.example.com
155
```
156

157
## Content Types
158

159
Both controllers support multiple content types:
160
- `application/json` - Standard JSON format
161
- `application/hal+json` - HAL (Hypertext Application Language) JSON format
162

163
## Group-based Documentation
164

165
Both controllers support documentation groups, allowing you to serve different API documentation for different parts of your application:
166

167
```java
168
// Multiple Docket beans create different groups
169
@Bean
170
public Docket publicApi() {
171
    return new Docket(DocumentationType.SWAGGER_2)
172
        .groupName("public")
173
        .select()
174
        .apis(RequestHandlerSelectors.basePackage("com.example.public"))
175
        .build();
176
}
177

178
@Bean
179
public Docket adminApi() {
180
    return new Docket(DocumentationType.SWAGGER_2)
181
        .groupName("admin")
182
        .select()
183
        .apis(RequestHandlerSelectors.basePackage("com.example.admin"))
184
        .build();
185
}
186
```
187

188
Access different groups:
189
- `/v2/api-docs` - Default group
190
- `/v2/api-docs?group=public` - Public API group
191
- `/v2/api-docs?group=admin` - Admin API group
192

193
## Request Handling
194

195
### WebMVC Implementation
196

197
- Uses `HttpServletRequest` for accessing request information
198
- Resolves hostname and port from servlet request
199
- Supports servlet-specific features and filters
200
- Compatible with Spring Security servlet configurations
201

202
### WebFlux Implementation
203

204
- Uses `ServerHttpRequest` for accessing request information
205
- Reactive, non-blocking request handling
206
- Resolves hostname from reactive request URI
207
- Compatible with Spring Security WebFlux configurations
208

209
## Response Format
210

211
Both controllers return `ResponseEntity<Json>` where:
212
- **Success (200)**: Returns JSON-formatted Swagger 2 specification
213
- **Not Found (404)**: When specified documentation group doesn't exist
214

215
Example success response structure:
216
```json
217
{
218
  "swagger": "2.0",
219
  "info": {
220
    "title": "API Documentation",
221
    "version": "1.0.0"
222
  },
223
  "host": "localhost:8080",
224
  "basePath": "/",
225
  "paths": {
226
    "/api/users": {
227
      "get": {
228
        "summary": "Get all users",
229
        "responses": {
230
          "200": {
231
            "description": "Successful operation"
232
          }
233
        }
234
      }
235
    }
236
  }
237
}
238
```
239

240
## Integration with Swagger UI
241

242
These endpoints are designed to work seamlessly with Swagger UI:
243

244
```javascript
245
// Swagger UI configuration
246
SwaggerUIBundle({
247
  url: 'http://localhost:8080/v2/api-docs',
248
  dom_id: '#swagger-ui',
249
  presets: [
250
    SwaggerUIBundle.presets.apis,
251
    SwaggerUIStandalonePreset
252
  ]
253
});
254
```
255

256
## Error Handling
257

258
Both controllers handle common error scenarios:
259
- **Missing Documentation Group**: Returns 404 with appropriate logging
260
- **Invalid Group Parameter**: Falls back to default group
261
- **Serialization Errors**: Handled by framework error handling
262

263
## Conditional Loading
264

265
Controllers are conditionally loaded based on classpath:
266
- **WebMVC Controller**: Only when servlet API is present
267
- **WebFlux Controller**: Only when reactive web stack is present
268

269
This ensures the appropriate controller is used based on your application type.