Spring Boot 集成 Swagger

最新推荐文章于 2022-09-06 09:14:26 发布

KeanePeng

最新推荐文章于 2022-09-06 09:14:26 发布

阅读量363

点赞数

CC 4.0 BY-SA版权

分类专栏： Spring 文章标签： spring spring boot swagger

本文链接：https://blog.youkuaiyun.com/csdm_APeng/article/details/101210683

Spring 专栏收录该内容

2 篇文章

订阅专栏

本文介绍了如何在 Spring Boot 项目中集成 Swagger，通过添加相关依赖和配置，使用 Swagger 自动生成 RESTful 风格的 Web 服务文档。利用 Swagger 提供的注解如 @Api, @ApiOperation, @ApiParam 等，可以详细描述接口和参数，提高文档的可读性。" 119872819,569322,Scratch编程实践：寻找宝石迷宫挑战,"['Scratch', '编程实践', '蓝桥杯', '电子学会等级考试', '儿童编程']

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。在 Spring Boot 中可以通过集成 Swagger 的方式完成文档的自动生成并保持完整的一致性，集成步骤如下：

添加 Swagger 相关依赖

<!-- 用于扫描接口配置 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- 用于显示文档页面 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

启用 Swagger 文档配置

@Configuration
@EnableSwagger2
@WebContext
public class SwaggerConfig {

    @Bean
    public Docket petApi() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        
        // 配置文档基本描述信息
        docket.apiInfo(apiInfo());
        // 配置全局参数
        docket.globalOperationParameters(buildGlobalOperationParameters());
        
        // 配置文档接口描述：
        // 1. 接口扫描基本包范围
        // 2. 接口统一前缀
        docket.select()
                .apis(RequestHandlerSelectors.basePackage("pwc.taxtech"))
                .paths(PathSelectors.regex("/api/.*"))
                .build();
                
        return docket;
    }

    private List<Parameter> buildGlobalOperationParameters() {
        List<Parameter> parameterList = new ArrayList<Parameter>();
        
        // 此处配置了公用的授权参数位于请求头中
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        parameterBuilder.name("Authorization").description("Bearer [JWT token]").modelRef(new ModelRef("string"))
                .parameterType("header").required(false).build();
        parameterList.add(parameterBuilder.build());
        
        return parameterList;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("文档标题")
                .description("文档描述")
                .version("文档版本")
                .build();
    }
}

描述接口信息

可以通过 @Api, @ApiOperation, @ApiParam 等一系列的注解描述接口和参数信息，使得文档更具有可读性，更多的相关注解请查看官方文档。

@Api("用户接口")
@RestController
@RequestMapping("/user")
public class UserController {
    
    @ApiOperation(value = "接口名称", notes = "接口详细描述")
    @GetMapping("/{id}")
    public User getUser(@ApiParam("用户 ID") @PathVariable String id) {
        User user = new User();
        // ...
        return user;
    }
}