SpringBoot整合Swagger2，让接口文档管理变得更简单

蔚落 2023-10-10 18:17 28阅读 0赞

在软件开发的过程中，接口文档的编写往往是一个非常重要的环节，因为它是前端和后端沟通的桥梁，帮助团队更好地协作。然而，手动编写接口文档不仅耗费时间，还容易出错，因此我们需要一种简单的方法来管理接口文档。在这篇文章中，我将介绍SpringBoot整合Swagger2的简单方法，以帮助您更好地管理接口文档。

### 1. 什么是Swagger2 ###

在开始介绍SpringBoot整合Swagger2的步骤之前，让我们谈一下Swagger2是什么。Swagger2是一种RESTful API文档生成工具，能够自动化生成API文档，并提供交互式文档，以方便开发人员使用。Swagger2不仅可以生成接口文档，还可以生成模拟数据，以方便前后端协作。

### 2. 添加Swagger2依赖 ###

在Spring Boot应用中使用Swagger2需要添加如下Maven依赖：

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>{latest-version}</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>{latest-version}</version>
    </dependency>

其中\{latest-version\}需要替换成最新版本号。

### 3. 配置Swagger2 ###

配置Swagger2并不困难，只需要增加一个SwaggerConfig类即可，代码如下：

@Configuration
    @EnableSwagger2
    public class SwaggerConfig {
        
        @Bean
        public Docket api() {
        
            return new Docket(DocumentationType.SWAGGER_2)
                    .select()
                    .apis(RequestHandlerSelectors.any())
                    .paths(PathSelectors.any())
                    .build();
        }
    }

其中：

*  `@Configuration`表示这是一个配置类；
 *  `@EnableSwagger2`表示开启Swagger2的支持；
 *  `Docket`是Swagger2的配置类，用于配置Swagger2的相关信息；
 *  `DocumentationType.SWAGGER_2`表示采用Swagger2的规范；
 *  `RequestHandlerSelectors.any()`表示所有Controller都会被扫描；
 *  `PathSelectors.any()`表示所有路径都会被扫描。

### 4. 编写接口文档注释 ###

添加好Swagger2依赖和配置类后，接下来我们需要在Controller层的接口方法上编写注释。示例如下：

@RestController
    @RequestMapping("/user")
    @Api(tags = "用户管理")
    public class UserController {
        
    
        @ApiOperation("新增用户")
        @PostMapping("")
        public CommonResult addUser(@RequestBody User user) {
        
            // ...
        }
    
        @ApiOperation("删除用户")
        @DeleteMapping("/{id}")
        public CommonResult deleteUser(@PathVariable Long id) {
        
            // ...
        }
    
        @ApiOperation("修改用户")
        @PutMapping("/{id}")
        public CommonResult updateUser(@PathVariable Long id, @RequestBody User user) {
        
            // ...
        }
    
        @ApiOperation("查询用户详情")
        @GetMapping("/{id}")
        public User getUserById(@PathVariable Long id) {
        
            // ...
        }
    
        @ApiOperation("查询用户列表")
        @GetMapping("")
        public List<User> getUserList() {
        
            // ...
        }
    }

在上述代码中：

*  `@Api(tags = "用户管理")`表示这是一个"用户管理"模块的接口；
 *  `@ApiOperation("新增用户")`表示新增用户的接口；
 *  `@PostMapping("")`表示HTTP请求方法为POST，路径为""。

### 5. 查看接口文档 ###

添加好接口文档注释后，我们就可以通过访问Swagger2的UI来查看接口文档了。只需要在浏览器中输入"http://localhost:8080/swagger-ui.html"，就可以进入Swagger2的UI界面了。接口文档的效果可以参考下图：  
![在这里插入图片描述][abe3c3e50fc445079644932945dc477e.png]

### 6. 使用Swagger2的高级特性 ###

Swagger2不仅可以生成接口文档，还可以生成模拟数据，以方便前后端协作。通过使用Swagger2的高级特性，我们可以在测试阶段使用模拟数据进行开发，以提高开发效率。以下是一些使用Swagger2高级特性的示例：

*  `@ApiModel`：用于对响应数据进行注释，表示一个用户对象，包含userName和password字段。

@ApiModel("用户对象")
    public class User {
        
        @ApiModelProperty(value = "用户名", required = true)
        private String userName;
    
        @ApiModelProperty(value = "密码", required = true)
        private String password;
    
        // ...
    }

*  `@ApiResponses`：用于对响应状态码进行注释。

@ApiOperation("查询用户详情")
    @GetMapping("/{id}")
    @ApiResponses({
        
            @ApiResponse(code = 200, message = "成功"),
            @ApiResponse(code = 400, message = "请求错误"),
            @ApiResponse(code = 401, message = "未授权"),
            @ApiResponse(code = 403, message = "禁止访问"),
            @ApiResponse(code = 404, message = "资源不存在")
    })
    public User getUserById(@PathVariable Long id) {
        
        // ...
    }

*  `@ApiModelProperty`：用于对请求参数进行注释，表示请求参数为用户名。

@ApiOperation("查询用户")
    @GetMapping("")
    public List<User> getUserList(@ApiParam(value = "用户名") @RequestParam(required = false) String userName) {
        
        // ...
    }

### 7. 总结 ###

通过本文的介绍，我们了解了Swagger2的基本使用方法，并讲解了一些高级特性，让接口文档管理变得更加简单。在项目中使用Swagger2可以有效地提高开发效率，减少接口文档编写的工作量。希望本文对大家在接口文档管理方面有所帮助。

[abe3c3e50fc445079644932945dc477e.png]: https://img-blog.csdnimg.cn/abe3c3e50fc445079644932945dc477e.png

发表评论取消回复

表情：

评论列表（有 0 条评论，28人围观）

还没有评论，来说两句吧...

相关阅读

相关 SpringBoot整合Swagger2，让接口文档管理变得更简单

在软件开发的过程中，接口文档的编写往往是一个非常重要的环节，因为它是前端和后端沟通的桥梁，帮助团队更好地协作。然而，手动编写接口文档不仅耗费时间，还容易出错，因此我们需要一种简

蔚落/ 2023年10月10日 18:17/ 0 赞/ 29 阅读

相关 SpringBoot整合Swagger2接口文档

一、添加依赖 <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui

Love The Way You Lie/ 2023年10月06日 22:06/ 0 赞/ 21 阅读

相关 SpringBoot 集成Swagger2 管理API接口文档

Springboot项目中接口管理文档Swagger2的使用 1 添加依赖，本人使用的maven，必须建立springboot web项目。 <dependen

爱被打了一巴掌/ 2023年06月29日 14:58/ 0 赞/ 22 阅读

相关 springBoot配置swagger2，接口文档方便管理！

目录 1.起因 2.配置 3.使用 4.注解说明 @ApiImplicitParam 5. Swagger改版 --------------------

港控/mmm°/ 2023年02月27日 12:27/ 0 赞/ 7 阅读

相关 SpringBoot整合Swagger2生成接口API文档

前言：Swagger2是一个能够帮助我们快速生成RESTful接口API文档的一个工具，你可以在控制器上写上接口描述，参数描述等等，在生成的Swagger2接口文档中都有体现，

r囧r小猫/ 2022年12月07日 12:08/ 0 赞/ 304 阅读

相关 SpringBoot整合Swagger2生成接口文档

文章目录一、导入依赖二、配置Swagger类三、启动访问四、Swagger2注解详解五、把S

青旅半醒/ 2022年12月03日 09:08/ 0 赞/ 341 阅读

相关 SpringBoot整合Swagger生成接口文档

介绍: Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源

痛定思痛。/ 2022年04月23日 11:54/ 0 赞/ 431 阅读

相关 SpringBoot整合Swagger2实现在线生成接口文档

源码获取 GitHub：https://github.com/291685399/springboot-learning/tree/master/springboot-

旧城等待，/ 2022年01月16日 15:19/ 0 赞/ 441 阅读

相关 SpringBoot_接口文档_Swagger2

SpringBoot\_接口文档\_Swagger2 依赖pom.xml 配置文件bootstrap.yml 配置源码 Swagger2常用注解

约定不等于承诺〃/ 2021年10月06日 03:34/ 0 赞/ 524 阅读

相关 SpringBoot整合Swagger实现接口文档

在项目开发中，一般都是前后端分离开发的，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发、维护。为了便于编写和维护稳定，可以使用Swagge

╰+攻爆jí腚メ/ 2021年07月25日 01:05/ 0 赞/ 560 阅读