跳转至

Spring Boot 集成 Swagger 文档

约 182 个字 170 行代码 3 张图片 预计阅读时间 3 分钟

引入依赖项

1
2
3
4
5
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.8.9</version>
</dependency>

安装依赖后即可使用：

  • 网页：http://server:port/context-path/swagger-ui.html
  • JSON：http://server:port/context-path/v3/api-docs

应用

在控制器上应用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
@RestController
@Slf4j
@RequestMapping("/route/")
@Tag(name = "Route Management", description = "Route import operations")
public class RouteController {

    @Autowired
    RouteService routeService;

    @PostMapping(value = "/import", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    @Operation(
            summary = "Import route from GPX file",
            description = "Import route from GPX file"
    )
    public BaseResponse importRouteFromGpx(
            @Parameter(
                    description = "GPX File",
                    required = true
            )
            @RequestPart("gpxFile") MultipartFile gpxFile,
            @Parameter(
                    description = "Name of the route",
                    example = "Test Route"
            )
            @RequestPart(value = "name", required = false) String name,
            @Parameter(
                    description = "Description of the route",
                    example = "Test Desc"
            )
            @RequestPart("description") String description,
            @Parameter(
                    description = "Transform coordinate or not",
                    example = "true"
            )
            @RequestPart("transformCoordinate") Boolean transformCoordinate,
            @Parameter(
                    description = "Original coordinate type",
                    example = "wgs84",
                    deprecated = true
            )
            @RequestPart("coordinateType") String coordinateType,
            @Parameter(
                    description = "Coordinate type that want to transform",
                    example = "gcj02"
            )
            @RequestPart("transformedCoordinateType") String transformedCoordinateType
    ) {
        ...
    }

    @GetMapping("/")
    @Operation(
            summary = "List route",
            description = "List route of current user"
    )
    public BaseResponse getRouteList(
            @Parameter(
                    description = "Page number",
                    example = "1"
            )
            @RequestParam(value = "page", required = false, defaultValue = "1")
            Integer page,
            @Parameter(
                    description = "Page size",
                    example = "10"
            )
            @RequestParam(value = "size", required = false, defaultValue = "10")
            Integer size,
            @Parameter(
                    description = "User ID",
                    example = "1",
                    deprecated = true
            )
            @RequestParam(value = "userId", required = false, defaultValue = "1")
            Long userId
    ) {
        ...
    }
}

1
2
3
4
5
6
7
8
@Data
@Builder
public class BaseResponse<T> {
    private Integer code;
    private String message;
    private T data;
    ...
}

对应的页面
对应的页面

在实体类上应用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
@lombok.Data
@lombok.Builder
@lombok.AllArgsConstructor
@lombok.NoArgsConstructor
@Schema(description = "Route Information")
public class RouteModel {
    @Schema(description = "Route ID", name = "id", example = "1")
    Long id;
    @Schema(description = "Creation Time", example = "2023-01-01T00:00:00.000Z")
    LocalDateTime createTime;
    @Schema(description = "Update Time", example = "2023-01-01T00:00:00.000Z")
    LocalDateTime updateTime;
    @Schema(description = "Creator", example = "DingJunyao")
    String createUser;
    @Schema(description = "Updater", minLength = 5, maxLength = 20)
    String updateUser;
    @Schema(description = "Route Name", deprecated = true)
    String name;
    @Schema(description = "Description")
    String description;
    @Schema(description = "Route Points Collection")
    List<RoutePointModel> points;
    @Schema(description = "Coordinate Type", allowableValues = {"wgs84", "gcj02", "bd09"})
    String coordinateType;
    @Schema(description = "Transformed Coordinate Type", allowableValues = {"wgs84", "gcj02", "bd09"})
    String transformedCoordinateType;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
@PostMapping("/")
@Operation(
        summary = "Get area info",
        description = "Get area info of first point of route"
)
public BaseResponse<AreaInfo> index(
        @Parameter(description = "Route Model", required = true)
        @RequestBody RouteModel routeModel
) {
    ...
}

对应的页面
对应的页面

Request Body 部分的 Example Value 如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
  "id": 1,
  "createTime": "2023-01-01T00:00:00.000Z",
  "updateTime": "2023-01-01T00:00:00.000Z",
  "createUser": "DingJunyao",
  "updateUser": "string",
  "description": "string",
  "points": [
    {
      "id": 0,
      "createTime": "2025-07-17T09:06:11.707Z",
      "updateTime": "2025-07-17T09:06:11.707Z",
      "createUser": "string",
      "updateUser": "string",
      "index": 0,
      "time": "2025-07-17T09:06:11.707Z",
      "elapsedTime": 0.1,
      "longitude": 0.1,
      "latitude": 0.1,
      "transformedLongitude": 0.1,
      "transformedLatitude": 0.1,
      "elevation": 0.1,
      "distance": 0.1,
      "course": 0.1,
      "speed": 0.1,
      "province": "string",
      "city": "string",
      "area": "string",
      "provinceEn": "string",
      "cityEn": "string",
      "areaEn": "string",
      "roadNum": "string",
      "roadName": "string",
      "roadNameEn": "string",
      "memo": "string"
    }
  ],
  "coordinateType": "wgs84",
  "transformedCoordinateType": "wgs84"
}

可以看到，遵循了设定的默认值和给定值。

切换到 Schema，可以看到详细的信息，包括限制：

Schema 可以看到详细的信息
Schema 可以看到详细的信息

不同的注解

一些文档里面使用的是 SpringFox，其中的注解和 springdoc 不一样，使用时要注意（左 SpringFox，右 springdoc）：

  • @Api → @Tag
  • @ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
  • @ApiImplicitParam → @Parameter
  • @ApiImplicitParams → @Parameters
  • @ApiModel → @Schema
  • @ApiModelProperty(allowEmptyValue = true) → @Schema(nullable = true)
  • @ApiModelProperty → @Schema
  • @ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
  • @ApiParam → @Parameter
  • @ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")

参考资料