0
# Springfox Swagger2
1

2
Springfox Swagger2 provides comprehensive Swagger 2 API documentation integration for Spring WebMVC and WebFlux applications. It automatically generates OpenAPI specifications from Spring controllers and models, offering seamless integration with Spring Boot through autoconfiguration.
3

4
## Package Information
5

6
- **Package Name**: springfox-swagger2
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: io.springfox
10
- **Artifact ID**: springfox-swagger2
11
- **Version**: 2.10.5
12

13
**Maven:**
14
```xml
15
<dependency>
16
    <groupId>io.springfox</groupId>
17
    <artifactId>springfox-swagger2</artifactId>
18
    <version>2.10.5</version>
19
</dependency>
20
```
21

22
**Gradle:**
23
```gradle
24
implementation 'io.springfox:springfox-swagger2:2.10.5'
25
```
26

27
## Core Imports
28

29
```java
30
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
31
import springfox.documentation.swagger2.annotations.EnableSwagger2WebFlux;
32
```
33

34
## Basic Usage
35

36
**WebMVC Integration:**
37
```java
38
import org.springframework.context.annotation.Configuration;
39
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
40

41
@Configuration
42
@EnableSwagger2WebMvc
43
public class SwaggerConfig {
44
    // Configuration class automatically sets up Swagger 2 documentation
45
}
46
```
47

48
**WebFlux Integration:**
49
```java
50
import org.springframework.context.annotation.Configuration;
51
import springfox.documentation.swagger2.annotations.EnableSwagger2WebFlux;
52

53
@Configuration
54
@EnableSwagger2WebFlux
55
public class SwaggerConfig {
56
    // Configuration class automatically sets up Swagger 2 documentation
57
}
58
```
59

60
## Architecture
61

62
Springfox Swagger2 is built around several key components:
63

64
- **Enable Annotations**: Simple annotations to activate Swagger 2 documentation generation
65
- **Auto-Configuration**: Spring Boot integration that automatically configures required beans and mappings
66
- **Documentation Mappers**: Convert Springfox documentation models to Swagger 2 specification format
67
- **Web Controllers**: Expose Swagger JSON documentation via REST endpoints
68
- **JSON Serialization**: Custom Jackson module for proper Swagger 2 JSON formatting
69

70
## Capabilities
71

72
### Setup and Configuration
73

74
Easy activation of Swagger 2 documentation generation through Spring configuration annotations. Supports both WebMVC and WebFlux application types.
75

76
```java { .api }
77
@EnableSwagger2WebMvc
78
public @interface EnableSwagger2WebMvc;
79

80
@EnableSwagger2WebFlux
81
public @interface EnableSwagger2WebFlux;
82
```
83

84
[Configuration](./configuration.md)
85

86
### API Documentation Generation
87

88
Core functionality that converts Spring application documentation into Swagger 2 specification format through comprehensive mapping capabilities.
89

90
```java { .api }
91
public abstract class ServiceModelToSwagger2Mapper {
92
    public abstract Swagger mapDocumentation(Documentation from);
93
}
94
```
95

96
[Documentation Generation](./documentation-generation.md)
97

98
### Web Integration
99

100
REST endpoints and controllers that serve generated Swagger 2 JSON documentation to clients and Swagger UI applications.
101

102
```java { .api }
103
public class Swagger2ControllerWebMvc {
104
    public ResponseEntity<Json> getDocumentation(
105
        @RequestParam(value = "group", required = false) String swaggerGroup, 
106
        HttpServletRequest servletRequest
107
    );
108
}
109

110
public class Swagger2ControllerWebFlux {
111
    public ResponseEntity<Json> getDocumentation(
112
        @RequestParam(value = "group", required = false) String swaggerGroup, 
113
        ServerHttpRequest request
114
    );
115
}
116
```
117

118
[Web Integration](./web-integration.md)
119

120
### JSON Serialization
121

122
Customized Jackson module for proper Swagger 2 JSON serialization with support for vendor extensions and example values.
123

124
```java { .api }
125
public class Swagger2JacksonModule extends SimpleModule implements JacksonModuleRegistrar {
126
    public void maybeRegisterModule(ObjectMapper objectMapper);
127
    public void setupModule(SetupContext context);
128
}
129
```
130

131
[JSON Serialization](./json-serialization.md)
132

133
## Configuration Properties
134

135
- `springfox.documentation.swagger.v2.host` - Override hostname in generated Swagger specification
136
- `springfox.documentation.swagger.v2.path` - Custom path for API documentation endpoint (default: /v2/api-docs)
137

138
## Common Types
139

140
```java { .api }
141
// Core Springfox types used throughout the API
142
interface Documentation {
143
    // Springfox documentation model
144
}
145

146
interface DocumentationCache {
147
    Documentation documentationByGroup(String groupName);
148
}
149

150
interface JsonSerializer {
151
    Json toJson(Object object);
152
}
153

154
// Swagger 2 model types
155
class Swagger {
156
    String getHost();
157
    String getBasePath();
158
    void host(String host);
159
    void basePath(String basePath);
160
}
161

162
class Json {
163
    // JSON wrapper for serialized Swagger documentation
164
}
165
```