springboot2.x基础教程:Swagger详解给你的接口加上文档说明
距离上次更新已经过了 700 天,文中部分内容可能已经过时,如有疑问,请在下方留言。
Springboot2.x基础教程:Swagger详解给你的接口加上文档说明
相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。 SpringBoot集成Swagger能够通过很简单的注解把接口描述清楚,生成可视化文档页面。 原生的Swagger-ui界面很粗糙,这里用knife4j-spring-ui替代。
一个好的HTTP接口文档描述
- 写清楚接口的请求路径: QueryPath: /user/login
- 写清楚接口的请求方法类型: GET/POST/DELETE/PUT
- 写清楚接口的业务含义,使用场景
- 写清楚接口的入参:参数描述、参数类型、参数结构、参数是否必传
- 写清楚接口的返回类型:返回的数据结构,异常状况
SpringBoot集成Swagger
项目引入依赖
SpringBoot关于Swagger配置
把此Swagger配置粘入项目即可
Swagger的具体使用
各个注解的作用
- @Api 放在类上介绍类的作用
- @ApiOperation 放在方法上介绍方法的作用
- @ApiImplicitParam介绍入参说明
- @ApiResponse介绍返回状态
- @ApiModel、@ApiModelProperty介绍入参是对象,返回是对象字段说明
代码示例
接口文档效果
这里访问的是http://localhost:8080/doc.html,knife4j-spring-ui还有相比原生还有更多强大的功能,大家自行发现。 千里之行,始于足下。这里是SpringBoot教程系列第二篇,所有项目源码均可以在我的GitHub上面下载源码。
版权声明:
本站所有文章除特别声明外,均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来自
编程之家!
喜欢就支持一下吧