为Springboot添加Swagger

一、Swagger3使用及好处

  1. 在如今前后端分离的时代,swagger能非常好的让前后端同学各司其职,根据API文档开发,提升效率
  2. Swagger3能非常明晰的显示API接口说明,包括方法类型、输入输出,以及参数类型,返回值等,且针对参数及实体有非常详细的注释说明,让大家对接口本身功能及调用更加明晰
  3. Swagger3本身也可以通过try it ot来快速调试问题,十分方便
  Swagger是一个用于自动生成在线接口文档的框架,并可在线测试接口,可以很好的跟Spring结合,只需要添加少量的代码和注解即可,而且在接口变动的同时,即可同步修改接口文档,不用再手动维护接口文档

二、为Springboot添加Swagger3

    1. 初始化生成Springboot结构,该部分不再详细描述,可以看之前介绍 [https://www.jianshu.com/p/7664e77bab2d](https://www.jianshu.com/p/7664e77bab2d)
    2. 添加maven依赖

image.png

3. 添加swagger3配置
image.png

4. 添加测试实体(用户实体)
image.png

- 这里有一点,传统JAVA大家可能会去写get / set, 后面大家慢慢使用IDE推荐的自动生成Getter/Setter, 但使用Springboot后大家可以使用lombok插件,对于属性使用非常文件,只需要在类里加入@Data注解即可。那么如何安装lombok插件呢,大家可以在File->Settings->Plugins里搜索lombok, 搜索到安装即可,当然有可能出现在MarketPlace中无法找到该插件,此时可能是因为网络无法访问marketplace,大家可以在后面的设置里添加代理地址http://plugins.jetbrains.com,然后搜索,当然最好是重启下idea
image.png

- 完成后在pom.xml中添加lombok依赖
image.png

- 这里还有一点需注意,为了让实体的属性及实体本身注释也显示出来,这里需要加上ApiModel的注解,针对UserEntity类加入@ApiModel(value = "UserEntity", description = "用户信息实体"),针对其下属性加下@ApiModelProperty注解
5. Swagger使用,在restcontroller中针对类及方法加相关注解
- 在接口类上添加@Api(tags = "操作接口"),tags的值是该类的作用,在文档页面会显示,value不会显示
- 在需要生成文档的接口上添加注解@ApiOperation
- 对请求参数添加@ApiParam
image.png

三、最终显示结果情况

     右键Run SpringbootswaggerApplication,启动完成后,在浏览器中输入[http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html),显示如下
image.png

- 打开用户控制器,默认显示用户控制器下3个API方法


image.png

- 打开添加用户信息后如下:


image.png

如:添加一个姓名:test, 性别:男, 年龄: 29,点击Excute后正常返回true,用户添加成功
- 打开“获取用户信息列表”(无参),Excute后显示如下 :
image.png

- 打开“通过用户名获取用户信息”,显示如下:


image.png

try it out后,在用户姓名里输入"jimmy",结果如下:
image.png

文章参考文献地址:

  1. SpringBoot整合Swagger3生成接口文档https://zhuanlan.zhihu.com/p/161947638
  2. SPRINGBOOT配置SWAGGER接口文档参数及返回值注释详细操作:[https://www.freesion.com/article/3595581092/]
最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
平台声明:文章内容(如有图片或视频亦包括在内)由作者上传并发布,文章内容仅代表作者本人观点,简书系信息发布平台,仅提供信息存储服务。

推荐阅读更多精彩内容