SpringBoot集成Swagger2在线文档
SpringBoot集成Swagger2在线文档
前言
不得不说,前后端分离开发的工作方式给我们带来诸多好处, 让前后端攻城狮们顺畅了不少
后端给前端提供良好的接口文档是一种品质,也会减少彼此的沟通成本
这里推荐小伙伴们一款在线、实时更新接口文档工具,Swagger2,解放双手不是梦,谁用谁知道
集成SpringBoot
添加依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.0</version>
</dependency>
创建配置文件
Swagger2Config.java
@Configuration
@EnableSwagger2
public class Swagger2Config { // 项目启动后,查看文档:http://{上下方路径}/swagger-ui.html
// 如,http://localhost:8080/swagger-ui.html // Swagger2 核心配置 docket
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2) // 指定api类型
.apiInfo(createApiInfo()) //定义文档汇总信息
.select().apis(RequestHandlerSelectors
.basePackage("cn.supergan.controller")) //指定controller包
.paths(PathSelectors.any()) //所有controller
.build();
} // 构建文档信息
public ApiInfo createApiInfo() {
return new ApiInfoBuilder()
.title("XXX 接口API") //文档页标题
.contact(new Contact("小动物不困", "https://www.supergan.cn", "abc@email.com")) //联系人信息
.description("XXX 接口API,实时更新,如有问题,及时沟通") //详细信息
.version("1.0") //文档版本号
.termsOfServiceUrl("https://www.supergan.cn") //网站地址
.build();
}
}
启动项目,访问文档首页http://localhost:8080/swagger-ui.html,效果如下
登录接口文档示例
代码
接口类:
PassportController.java
@Api(tags = "登录")
@RestController
public class PassportController {@ApiOperation(value = "登录", notes = "使用用户名和密码登录")
@ApiImplicitParams({
@ApiImplicitParam(value = "用户名", name = "username", required = true),
@ApiImplicitParam(value = "密码", name = "password", required = true)
})
@PostMapping("/login")
public JSONResult<Users> login(@RequestParam String username, @RequestParam String password) {
Users users = new Users();
// TODO 此处省略登录相关业务逻辑
users.setUsername(username);
users.setPassword(password);
return JSONResult.ok(users);
}
用户类:Users.java
@ApiModel(description = "用户")
@Data
public class Users {
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
}
响应类:
JSONResult.java
,统一接口的数据响应格式,小伙伴们可根据自己的需求改造和使用@Data
public class JSONResult<T> {
private Integer status;
private String message;
private T data; public JSONResult(ResultCode code) {
this.setMessage(code.getMessage());
this.setStatus(code.getStatus());
} public static <T> JSONResult<T> ok(T data) {
JSONResult<T> jsonResult = new JSONResult<T>(ResultCode.SUCCESS);
jsonResult.setData(data);
return jsonResult;
} @Getter
enum ResultCode {
SUCCESS(200, "OK"),
UN_KNOW_ERROR(500, "未知异常")
;
private Integer status;
private String message; ResultCode(Integer status, String message) {
this.status = status;
this.message = message;
}
}
}
效果
注解说明
@Api
@Api:用在请求的类上,说明该类的作用
tags="说明该类的作用"
value="该参数没什么意义,所以不需要配置"
示例
@Api(tags="APP用户注册Controller")
@ApiOperation
@ApiOperation:用在请求的方法上,说明方法的作用
value="说明方法的作用"
notes="方法的备注说明"
示例
@ApiOperation(value = "登录", notes = "使用用户名和密码登录")
@ApiImplicitParams
@ApiImplicitParams:用在请求的方法上,包含一组参数说明
@ApiImplicitParam:用在 @ApiImplicitParams 注解中,指定一个请求参数的配置信息
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
示例
@ApiImplicitParams({
@ApiImplicitParam(value = "用户名", name = "username", required = true),
@ApiImplicitParam(value = "密码", name = "password", required = true)
})
@ApiResponses
@ApiResponses:用于请求的方法上,表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
示例
@ApiResponses({
@ApiResponse(code=400,message="请求参数错误"),
@ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})
@ApiModel
@ApiModel:用于响应类上,表示一个返回响应数据的信息
(这种一般用在post创建的时候,使用@RequestBody这样的场景,
请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:用在属性上,描述响应类的属性
示例
@ApiModel(description = "用户")
@Data
public class Users {
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
}
总结
本文介绍了在SpringBoot中如何集成Swagger2,快速上手的用法,和主要注解的说明。
其中值得注意的是,上文中提到的JSONResult.java
,它的泛型申明,在接口文档中起到了描述data属性详情的作用。
以上内容足以让你在日常开发中轻松驾驭Swagger2
SpringBoot集成Swagger2在线文档的更多相关文章
- springboot使用swagger2创建文档
一.导入swagger2依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>spri ...
- SpringCloud微服务实战——搭建企业级开发框架(六):使用knife4j集成Swagger2接口文档
knife4j是为集成Swagger生成api文档的增强解决方案,前后端Java代码以及前端Ui模块进行分离,在微服务架构下使用更加灵活, 提供专注于Swagger的增强解决方案,不同于只是改善增强前 ...
- springboot集成restdocs输出接口文档
1.pom文件新增restdocs <dependency> <groupId>org.springframework.restdocs</groupId> ...
- SpringBoot整合Swagger2搭建API在线文档
Swagger,中文"拽"的意思,它是一个功能强大的在线API在线文档,目前它的版本为2.x,所以称为Swagger2.Swagger2提供了在线文档的查阅和测试功能.利用Swag ...
- springboot集成swagger2构建RESTful API文档
在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可 ...
- springboot集成swagger2,构建优雅的Restful API
swagger,中文“拽”的意思.它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅,而且还提供了在线文档的测试.另外swagger很容易构建restful风格的api,简单优雅 ...
- (转)第十一篇:springboot集成swagger2,构建优雅的Restful API
声明:本部分内容均转自于方志明博友的博客,因为本人很喜欢他的博客,所以一直在学习,转载仅是记录和分享,若也有喜欢的人的话,可以去他的博客首页看:http://blog.csdn.net/forezp/ ...
- (转) SpringBoot非官方教程 | 第十一篇:springboot集成swagger2,构建优雅的Restful API
swagger,中文“拽”的意思.它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅,而且还提供了在线文档的测试.另外swagger很容易构建restful风格的api,简单优雅 ...
- SpringBoot非官方教程 | 第十一篇:springboot集成swagger2,构建优雅的Restful API
转载请标明出处: 原文首发于:https://www.fangzhipeng.com/springboot/2017/07/11/springboot-swagger2/ 本文出自方志朋的博客 swa ...
随机推荐
- vue 学习 渲染、v-指令
vue渲染 在组件中data是一个方法里面的值要是一个对象return出去 export default { name: "HelloWorld", data() { return ...
- html学习笔记--xdd
<!DOCTYPE html> <html> <head> <title>HTML学习笔记</title> <meta charset ...
- find_all的用法 Python(bs4,BeautifulSoup)
find_all()简单说明: find_all() find_all() 方法搜索当前tag的所有tag子节点,并判断是否符合过滤器的条件 用法一: rs=soup.find_all('a') 将返 ...
- Mysql查询语句之排序查询
语法: /* select 查询列表 from 表 [where 筛选条件] order by 排序列表 [asc/desc] */ ①asc为升序,desc为降序,且默认为升序 ②order by子 ...
- C#笔记01——注释、进制、基本数据类型、量和输入输出函数
一.注释 1.单行注释 使用方法:行首加 ” //“: VS2019中的快捷键(以后如果不特加说明都是VS2019): 注释(CTRL+E,C): 取消注释(CTRL+E,U): 2.多行注释 使用方 ...
- 经典算法之K近邻(回归部分)
1.算法原理 1.分类和回归 分类模型和回归模型本质一样,分类模型是将回归模型的输出离散化. 一般来说,回归问题通常是用来预测一个值,如预测房价.未来的天气情况等等,例如一个产品的实际价格为500元, ...
- scrapy下载中间件结合selenium抓取全国空气质量检测数据
1.所需知识补充 1.下载中间件常用函数 process_request(self, request, spider): 当每个request通过下载中间件是,该方法被调用 process_reque ...
- AI手写输入法 - pytorch从入门到入道(二)
本章承接上一篇的手写数字识别,利用训练好的模型,结合pyqt画板,实现简易手写输入法,为"hello world"例子增添乐趣. pyqt是开发图形界面的框架,可以百度查找相关资料 ...
- c堆排序
#include<stdio.h> #include<stdlib.h> /* p是循环输出的下表*/ ; /*堆调整算法*/ /* r[]数组 , 根结点的编号为k,最后一个 ...
- input 输入框 只能输入数字、字母、汉字等
1.文本框只能输入数字代码(小数点也不能输入) <input onkeyup="this.value=this.value.replace(/\D/g,'')" onafte ...