【笔记】SpringBoot项目整合Swagger

发表于 更新于 阅读次数：

前言

SpringBoot项目整合Swagger，实现自动生成API文档

引入依赖

Spring 3.x

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

Spring 2.x

pom.xml
1
2
3
4
5
<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.8.0</version>
</dependency>

创建配置类

Spring 3.x

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import org.springdoc.core.models.GroupedOpenApi;
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@OpenAPIDefinition(
    info = @Info(
        title = "API文档",
        description = "接口文档"
        version = "1.0",
    )
)
@Configuration
public class SpringDocConfig {
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
            .group("public-apis")
            .pathsToMatch("/api/**")
            .build();
    }
}

Spring 2.x

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import org.springframework.context.annotation.Configuration;


@Configuration
@OpenAPIDefinition(
    info = @Info(
        title = "API文档",
        description = "接口文档",
        version = "1.0"
    )
)
public class SpringDocConfig {
}

标注Controller

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;

@RestController
public class SampleController {
    
    @Operation(
        summary = "接口简要描述",
        description = "详细说明接口功能",
        tags = {"public-apis"}  // 对应SwaggerConfig中的分组名
    )
    @ApiResponse(
        responseCode = "200",
        description = "成功响应描述"
    )
    @GetMapping("/api/demo")
    public ResponseEntity<?> demoMethod(
        @Parameter(description = "用户ID", required = true, example = "123") 
        @RequestParam Long userId
    ) {
        // ...
    }
}

标注实体类

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import io.swagger.v3.oas.annotations.media.Schema;

@Schema(
    name = "UserDTO", 
    description = "用户传输对象"
)
public class UserDTO {
    
    @Schema(
        description = "用户姓名",
        example = "张三",
        requiredMode = Schema.RequiredMode.REQUIRED
    )
    private String name;

    @Schema(
        description = "年龄",
        minimum = "0",
        maximum = "150",
        example = "25"
    )
    private Integer age;

}

访问SwaggerUI

获取SwaggerJSON文件

完成

参考文献

博客园——戒爱学Java
博客园——Code技术分享