SpringBoot如何优雅的整合Swagger Api自动生成文档

目录前言 整合swagger api 自定义配置信息 简单使用 Swagger常用注解Api标记 ApiOperation标记 ApiParam标记 ApiModel标记 ApiModelProperty标记 ApiIgnore标记 ApiImplicitParam标记 ApiImplicitParams标记 总结

前言

一个好的可持续交付的项目，项目说明，和接口文档是必不可少的，swagger api 就可以帮我们很容易自动生成api 文档，不需要单独额外的去写，无侵入式，方便快捷大大减少前后端的沟通方便查找和测试接口提高团队的开发效率方便新人了解项目，剩余的时间就可以去约妹子啦

整合swagger api

这里我们自己去整合swagger api比较麻烦，要导入好几个包，有大神帮我们写好了轮子kinfe4j直接对应SpringBoot的启动项，而且在不影响原来使用功能上界面ui做了美化功能做了增强 我们直接整合这个就好了

com.github.xiaoymin knife4j-spring-boot-starter 3.0.1

正如官网所说

kinfe4j官方文档点击这里

自定义配置信息

为我们为swagger配置更多的接口说明

抽出api文档配置模版信息为属性文件方便复用

简单使用

在你的Controller上添加swagger注解

@Slf4j @Api(tags = "登录") public class LoginController { private final IUsersService userService; @PostMapping("/login") @ApiOperation("用户登录") public String login(@RequestBody UserLoginParams userLoginParams) { Users u = userService.login(userLoginParams); return "ok"; } }

注意如启用了访问权限，还需将swagger相关uri允许匿名访问

/swagger**/** /webjars/** /v3/** /doc.html

重启服务，自带api文档访问链接为/doc.html界面如下:

相比较原来界面UI更加漂亮了，信息更完善功能更强大

Swagger常用注解

Api标记

用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源

参数：

tags：说明该类的作用，参数是个数组，可以填多个。 value="该参数没什么意义，在UI界面上不显示，所以不用配置" description = "用户基本信息操作"

ApiOperation标记

用于请求的方法上表示一个http请求的操作

参数:

value用于方法描述 notes用于提示内容 tags可以重新分组（视情况而用）

ApiParam标记

用于请求方法上对请求参数，字段说明；表示对参数的添加元数据（说明或是否必填等）

参数：

name–参数名 value–参数说明 required–是否必填

ApiModel标记

用于java实体类上表示对类进行说明，用于参数用实体类接收

参数：

value–表示对象名 description–描述 都可省略

ApiModelProperty标记

用于方法，字段； 表示对model属性的说明或者数据操作更改

参数：

value–字段说明 name–重写属性名字 dataType–重写属性类型 required–是否必填 example–举例说明 hidden–隐藏

@ApiModel(value="user对象",description="用户对象user") public class User implements Serializable{ private static final long serialVersionUID = 1L; @ApiModelProperty(value="用户名",name="username",example="xingguo") private String username; @ApiModelProperty(value="状态",name="state",required=true) private Integer state; private String password; private String nickName; private Integer isDeleted; @ApiModelProperty(value="id数组",hidden=true) private String[] ids; private List idList; //省略get/set }

ApiIgnore标记

用于请求类或者方法上，可以不被swagger显示在页面上

ApiImplicitParam标记

用于方法表示单独的请求参数

ApiImplicitParams标记

用于方法，包含多个 @ApiImplicitParam

参数：

name–参数名 value–参数说明 dataType–数据类型 paramType–参数类型 example–举例说明

@ApiOperation("查询测试") @GetMapping("select") //@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query") @ApiImplicitParams({ @ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"), @ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")}) public void select(){ }

总结

可以给实体类和接口添加注释信息 接口文档实时更新 在线测试 kinfe4j 在swagger API只做增强，不会改变原有任何使用，更多增加使用功能

点击这里进入kinfe4j官网文档

到此这篇关于SpringBoot如何优雅的整合Swagger Api自动生成文档的文章就介绍到这了,更多相关SpringBoot整合Swagger Api内容请搜索以前的文章或继续浏览下面的相关文章希望大家以后多多支持！

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。