springboot系列(十七):集成在线接口文档Swagger2|超级详细，建议收藏

Posted bug菌¹

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了springboot系列(十七):集成在线接口文档Swagger2|超级详细，建议收藏相关的知识，希望对你有一定的参考价值。

👨‍🎓作者：bug菌

🚫特别声明：原创不易，转载请附上原文出处链接和本文声明，谢谢配合。

🙏版权声明：文章里可能部分文字或者图片来源于互联网或者百度百科，如有侵权请联系bug菌处理。

​
【开发云】年年都是折扣价，不用四处薅羊毛

         嗨，家人们，我是bug菌呀，我又来啦。今天我们来聊点什么咧，OK，接着为大家更《springboot零基础入门教学》系列文章吧。希望能帮助更多的初学者们快速入门！

       小伙伴们在批阅文章的过程中如果觉得文章对您有一丝丝帮助，还请别吝啬您手里的赞呀，大胆的把文章 点亮👍吧，您的点赞三连( 收藏⭐️+关注👨‍🎓+留言📃)就是对bug菌我创作道路上最好的鼓励与支持😘。时光不弃🏃🏻‍♀️，创作不停💕，加油☘️

一、前言🔥

        今天，我要给大家介绍一个绝世好东西，你们没用过的小伙伴体验完后绝对会爱不释手，从此解脱我们的双手，真真真绝绝子，必须安利给你们。

        在日常开发过程中，想必有不少小伙伴都被写接口文档毒害过吧，好不容易写完文档，前端又跑来抱怨接口文档与实际情况不一致，然后自己又经常沉迷于编写及维护接口文档无法自拔，经常来不及更新，就造成了这种小插曲。但是接口文档对于我们而言，就跟注释一样，虽然经常会抱怨别人写的代码没有写注释，然而自己码代码的时候，最讨厌的，也是写注释（哈哈哈说出了大家的心声）。

        所以，到底有啥妙招能彻底摆脱这个泥潭呢？请接着往下看。

二、swagger介绍🔥

       我就不卖关子啦，相信在座的各位很多都已经用过，但是没关系，只要全世界还有一个没用过，我都会给他讲。

       那么，它究竟是何方神圣？登登登~，就是它啦，Swagger！

1️⃣概念

       Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。而且它还是全球最大的OpenAPI规范（OAS）API开发工具框架，且支持从设计和文档到测试和部署的整个API生命周期的开发。
       它的诞生，就是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

2️⃣优势

       Swagger的目标是为REST APIs 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。
       当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。

3️⃣重要特性

  • 代码侵入式注解。
  • 遵循YAML文档格式。
  • 非常适合三端（PC、ios及android）的API管理，尤其适合前后端完全分离的架构模式。
  • 减少没有必要的文档，符合敏捷开发理念。
  • 功能强大。

这不比你手写接口文档香么？(发自灵魂一问) 

那说到这，肯定很多小伙伴就蠢蠢欲动，跃跃欲试，坐立不安了，"这么好使，那不得赶紧教教我们，怎么用啊？"。

bug菌从容回答道："别急哈，容bug菌充个饥先，去去就回。"

十分钟过去了...

半个小时过去了...

... ...

一个小时过去后... ”好啦，兄弟萌，我来啦。“，那个男人终于回来了，"好啦，咱们接着往下看。"

三、集成Swagger🔥

        集成Swagger文档，你需要做两步，请按如下操作进行即可。

1️⃣引入依赖

        在项目的pom依赖配置中添加对于的swagger依赖配置。

<!--swagger2-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
 <!--排除传递性依赖(默认依赖指定版本的models跟annotations)，避免报错-->
    <exclusions>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
        </exclusion>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<!--Swagger第三方ui-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.2</version>
</dependency>

<!--提供Swagger API注解-->
<dependency>
    <groupId>io.swagger</groupId> 
    <artifactId>swagger-annotations</artifactId>
    <version>1.5.21</version>
</dependency>

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.5.21</version>
</dependency>

       是不是觉得看着有点多，说实话也不多，等你体验了，你就不会觉得这有啥，如上就是Swagger依赖生态啦，基本需要用到的我都配了。由于原生UI界面不是很好看，我就给换了，你们也可以自己选择。

       这是我是集成了xiaoymin开源的ui界面：可就很美观了呀，你们要是好奇，你们可以自己玩一下原生的ui是啥样子，这里就不一一给大家演示了哈。

​

2️⃣config文件配置

        依赖都引用全了，接着就是要配置一下swagger，指定几个属性及访问swagger界面url。

package com.example.demo.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * swagger配置
 *
 * @Author luoyong
 * @Date 2021-06-01 13:00
 */
@Configuration //必须存在
@EnableSwagger2 //必须存在
public class SwaggerConfig 

    @Bean
    public Docket customDocket() 
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))//对应你controller目录
                .paths(PathSelectors.any())
                .build();
    

    private ApiInfo apiInfo() 
        return new ApiInfoBuilder()
                .title("swagger 接口文档")  //指定文档标题
                .contact(new Contact("luoyong", "", ""))  //指定作者
                .description("swagger-bootstrap-ui")  //接口文档描述
                .termsOfServiceUrl("http://localhost:8080") //指定在线接口文档访问url
                .version("1.0")  //指定版本号
                .build();

       都配置好后，咱们重启项目，然后浏览器输入url地址：http://localhost:8080/doc.html

你将会发现，这不就是我上方所截图的UI界面嘛。没错，这样就表明已经配置好啦。

四、实战演示🔥

        如下就给大家演示一下，也就是几个api的使用，就搞定啦，是不是感jio很简单呐。

1️⃣配置controller

        首先我们将会用到两个注解@Api与@ApiOperation ，具体注解使用及作用我会在下面进行介绍，这里就直接进行上手使用环节。

/**
 * 用户管理分发器
 */
@RestController@RequestMapping("/user")
@Api(tags = "用户管理模块",description = "用户管理模块") //修饰整个类，进行描述
public class UserController 

@Autowired
private UserService userService;
@GetMapping("/get-users")
public List<UserEntity> getUserList() 
    return userService.getUsers();

重启下项目，神奇的一幕发生了。请看下方截图：

​

我们再来使用@ApiOperation，如下对接口进行描述：

/**
 * 不分页查询db所有用户信息
 */
@GetMapping("/get-users")
@ApiOperation(value = "不分页查询db1所有用户信息",notes = "不分页查询db1所有用户信息")
public List<UserEntity> getUserList() 
    return userService.getUsers();

再次重启下项目，请看：

​

        出现了你刚配置的文字描述，这也就是方便给前端开发进行接口详细描述提醒。

然后你点击下方调试，点击发送，即：

​

 结果返回：

​

        是不是很有postman的即视感，没错，在线调试也是被集成进去了。无论对自己还是前端开发都及其方便，毕竟测试接口很方便啊，不需要像postman输入完整访问路径等相关接口调用信息，一切操作都变得很简单。有没有？直接发送请求即可。

2️⃣配置entity等参数结构体

我们再来进行一个参数体配置，看看会发生什么？

@Data
@ApiModel(value = "查询用户参数体合集",description = "查询用户参数体合集")public class QueryUserInfoModel 
   
    @ApiModelProperty("性别")
    private String sex;

    @ApiModelProperty("班级名称")
    private String className;

    @ApiModelProperty("用户ids")
    private List<Integer> userIds;

然后再结合上方所讲到的，对接口进行描述。

/**
 * 根据用户ids等参数联合查询用户信息
 */
@PostMapping("/getUser-by-ids")
@ApiOperation(value = "根据用户ids等参数联合查询用户信息",notes = "根据用户ids等参数联合查询用户信息")
public List<UserInfoVo> getUserById(@RequestBody QueryUserInfoModel model)
    return userMapper.getUsersByIds(model.getUserIds());

        再次重启项目，我们可以看到对参数体都有了描述；是不是看着很爽。这样就对非开发人员使用也变得很通透了，一看就知道每个参数分别对应什么意思，而不再需要配置额外的文档进行辅助测试了，对前端对测试对非专业人士都很便利，所以赶紧集成到自己的项目中用起来吧。

​

        至于上方截图涉及到的是否必填一栏，也是来源于@ApiModelProperty 这个 注解，自带是否必填这个属性(required)，属性默认是false不必填，如果你要告诉前端及测试接口人员指定这个参数必须要填写，那你就把required属性设置值为true 即可，即表示该参数必填，如果不填，则肯定是不会通过接口调用的。

例如下方代码演示：表示该性别字段为必填参数。

@ApiModelProperty(value = "性别",required = true)

        如上我就是制定了性别这个字段，你在通过swagger文档进行接口调用的时候，假设没传，你知道会出现什么问题嘛？聪明人都知道，不就提示字段为空，然后接口调用失败了嘛。

具体详情咱们看swagger调用返回：请看如下：

​

接着我们将性别字段，随便填入一个值，再进行调用，这个时候我们再看。

​

 可以看到，接口调用成功了，数据查询也返回了。

        很明显是由于你设置了required = true 这个属性触发的提醒效果，不加这个属性，就表示该字段可填可不填。一般都是接口定义好，如果参数必填，就加上该字段，进行提醒相关人员接口调用的时候，这个参数是必填项，不填则无法接口调用咯。基本就是这么个使用情况啦。

       还有很多api如何使用，期待小伙伴们自行探索啦，这里就给大家演示了基本几个常用的，剩下的就靠大家的自觉性与积极性啦。

五、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

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

🔟@ApiImplicitParam

作用：一个请求参数。

🔠@ApiImplicitParams

作用：多个请求参数 。

        ... ...

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

六、总结🔥

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

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

       ok，以上就是我这期的全部内容啦，如果还想学习更多，你可以看看我的往期热文推荐哦，每天积累一个奇淫小知识，日积月累下去，你一定能成为令人敬仰的大佬的。好啦，咱们下期见~

七、往期推荐🔥

八、文末🔥

       如果还想要学习更多，小伙伴们可关注bug菌专门为大家创建的专栏《springboot零基础入门教学》，从无到有，从零到一！希望能帮助到更多小伙伴们。

​
【开发云】年年都是折扣价，不用四处薅羊毛

       我是bug菌，一名想走👣出大山改变命运的程序猿。接下来的路还很长，都等待着我们去突破、去挑战。来吧，小伙伴们，我们一起加油！未来皆可期，fighting！

        最后送大家两句我很喜欢的话，与诸君共勉！

☘️做你想做的人，没有时间限制，只要愿意，什么时候都可以start。

🍀你能从现在开始改变，也可以一成不变，这件事，没有规矩可言，你可以活出最精彩的自己。

​​​​

💌如果文章对您有所帮助，就请留下您的赞吧！(#^.^#)；

💝如果喜欢bug菌分享的文章，就请给bug菌点个关注吧！(๑′ᴗ‵๑)づ╭❤～；

💗如果对文章有任何疑问，还请文末留言或者加群吧；

💞鉴于个人经验有限，所有观点及技术研点，如有异议，请直接回复参与讨论(请勿发表攻击言论，谢谢）；

💕版权声明：原创不易，转载请附上原文出处链接和本文声明，版权所有，盗版必究！！！谢谢

以上是关于springboot系列(十七):集成在线接口文档Swagger2|超级详细，建议收藏的主要内容，如果未能解决你的问题，请参考以下文章

SpringBoot集成Swagger2在线文档

Springboot系列 集成接口文档swagger，使用，测试

Springboot系列 集成接口文档swagger，使用，测试

Spring Boot2 系列教程(十七)SpringBoot 整合 Swagger2

Spring Boot2 系列教程(十七)SpringBoot 整合 Swagger2

SpringBoot2.0系列教程Springboot框架添加Swagger2来在线自动生成接口的文档+测试功能