SpringBoot【十三(完结篇)】集成在线接口文档Swagger2

一、前言🔥

环境说明：Windows10 + Idea2021.3.2 + Jdk1.8 + SpringBoot 2.3.1.RELEASE

 

二、Swagger常用注解

由于Swagger 是通过注解的方式来生成对应的 API，在接口上我们需要加上各种注解来描述这个接口，所以对它常用的注解我们是必须要清楚的，要不然我讲这些也只是徒劳，

接下来我将关于 Swagger 注解的使用在教程进行详细讲解。请大家好好听~

1、@API 

作用：修饰整个类，描述Controller的作用。

代码演示：

@RestController
@RequestMapping("/user")
@Api(tags = "用户管理模块",description = "用户管理模块")
public class UserController {

}

演示截图：

2、@ApiOpration

作用：描述一个类的一个方法，或者说一个接口。

代码演示：

@GetMapping("/get-users")
@ApiOperation(value = "不分页查询所有用户信息",notes = "不分页查询所有用户信息")
public List<UserEntity> getUserList() {

}

演示截图：

3、@ApiParam

作用：单个参数描述。

代码演示：

@GetMapping("/getUser-by-id")
@ApiOperation(value = "根据用户id查询用户信息",notes = "根据用户id查询用户信息")
public UserEntity getUserById(@RequestParam(name = "userId")@ApiParam("请输入用户id") String userId){    return userMapper.getUserById(userId);
}

演示截图：

4、@ApiModel

作用：用对象来接收参数。

代码演示：

@ApiModel(value = "查询用户参数体",description = "查询用户参数体")
public class QueryUserInfoModel {
}

演示截图：

5、@ApiModelProperty

作用：用对象接收参数时，描述对象的一个字段。

代码演示：

@ApiModelProperty("发件人邮箱账号")
private String sendMailAccount;

@ApiModelProperty("收件人邮箱账号")
private String acceptMailAccount;

演示截图：

6、@ApiIgnore

作用：可以用在类、方法上，方法参数中，用来屏蔽某些接口或参数，使其不在页面上显示。

代码演示1：用在类上

@ApiIgnore
@RestController
@RequestMapping("/user")
@Api(tags = "用户管理模块",description = "用户管理模块")
public class UserController {

}

代码演示2：用在方法上

 @ApiIgnore
 @GetMapping("/get-users")
 @ApiOperation(value = "不分页查询db所有用户信息",notes = "不分页查询db所有用户信息")
 public ListgetUserList() {
     return userService.getUsers();
 }

 以上这个注解也是经常会被用到，如果接口暂时不上线，或者还未完善，我们就可以加上此注解，这样使用swagger文档的同事就不会看到这个接口，以免造成不必要的麻烦，接口报错啊？这接口怎么逻辑不对？等问题，是不是就很便利，二来你也不需要注释掉或者删除，所以这个注解大家还是要多练练加深印象哈。

**注意：**如下所介绍到的几个不是经常用到，我们就当拓展吧~以了解为主哈。你们不必花时间深入研究。

7、@ApiResponse

作用：在 Rest 接口或类上和 @ApiResponses 组合使用，组装返回参数说明。

8、@ApiResponses

作用:HTTP响应整体描述。

9、@ApiError

作用:发生错误返回的信息。

10、@ApiImplicitParam

作用：一个请求参数。

11、@ApiImplicitParams

作用：多个请求参数 。

... ...

其实还有一部分api，我就一一列举了，靠大家举一反三啦。

三、总结

       其实归根到底啊，使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个描述文件，连描述文件都不需要再去维护了。所有的信息，都在代码里面了。代码即接口文档，接口文档即代码，在线文档就替我们解决了文档书写及维护的百分之九十的工作，还是很感谢这些开源大佬们做出的贡献。

       至于为什么说是Springfox-swagger？其实呢Swagger 就可以看作是一个遵循了 OpenAPI 规范的一项技术，而 springfox 则是这项技术的具体实现。 就好比 Spring 中的 AOP 和 DI 一样，前者是思想，而后者是实现。

原文地址：https://blog.csdn.net/mf97532/article/details/144451179

免责声明：本站文章内容转载自网络资源，如本站内容侵犯了原著者的合法权益，可联系本站删除。更多内容请关注自学内容网（zxcms.com）！