springboot2.1.5结合swagger2生成在线接口API文档
- 记录下自己对swagger2的使用
- 第一步:在pom文件引入maven依赖
- 第二步:在controller类里面加入swagger注释
- 第三步:在controller中用到的自定义对象都需要加上swagger注解逐个说明
- 第四步:在application.properties里面加上API说明
- 第5步:在springboot的启动类上加上注解就可以了
- 最后附上使用后的效果
- 在线接口文档完成, 下一篇记录导出在线文档为离线的html和PDF
记录下自己对swagger2的使用
自己做后端接口开发的时候, 领导让我提供接口文档,当时自己只有postman的接口地址, 既然领导问到了, 那就做一个接口文档, 当时第一时间想想到了swagger2, 直接在线生成一份, 既简单又美观使用, 各种百度找资源,最后整理出一套比较新的
第一步:在pom文件引入maven依赖
在网上搜寻时发现有2种maven依赖可以引用,一种普通的maven依赖,一种是springboot的启动器,先尝试的第一种, 比springboot启动器配置复杂,而且是英文的,不符合我大中国的阅读习惯,最后生成的接口文档样式没有直接用启动器的直观,所以第一种就不多说了,直接上springboot的启动器依赖
<!--swagger 启动器-->
<dependency>
<groupId>com.battcn</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>2.1.5-RELEASE</version>
</dependency>
第二步:在controller类里面加入swagger注释
swagger注解的使用说明不懂的可以百度了解,很多,这里就不多说了
话不多说,直接上代码
/**
* author: 聂鹏
* email:122352701@qq.com
* description:测试接口
* create:2019/8/25
*/
@RestController
@Api(tags="测试接口")
public class TestController {
@GetMapping("/t")
@ApiOperation(value = "简单的测试接口", notes = "返回一个简单json",response=NpResult.class)
public NpResult test() {
return NpResult.success();
}
}
/**
* author: 聂鹏
* email:122352701@qq.com
* description:
* create:2019/8/25
*/
@RestController
@Api(tags="计费接口")
public class CountRuleController {
//计费
@PostMapping("/countFee")
@ApiOperation(value = "计算费用", notes = "根据传入的参数进行计算")
@ApiImplicitParam(name = "param", value = "请求的CountParam对象", required = true, dataType = "CountParam")
public NpResult countFee(@RequestBody CountParam param) {
//中间省略业务代码
return NpResult.success();
}
/**
* description:根据名字模糊查询计费方案
* @param name 名字
* @return NpResult
*/
@GetMapping("/getCountRule")
@ApiOperation(value = "查询计费方案",notes ="根据名字进行模糊查询")
@ApiImplicitParam(name = "name",value = "计费方案名字",required = true)
public NpResult getCountRule(@RequestParam String name) {
//中间省略业务代码
return NpResult.success();
}
/**
* description:启用新的计费方案
* @param id 主键
* @return NpResult
*/
@PostMapping("/updateStatus")
@ApiOperation(value = "启用计费方案", notes = "启用另一种计费方案")
@ApiImplicitParam(name = "id",value = "计费方案id",required = true,dataType="Integer")
public NpResult updateStatus(@RequestParam Integer id) {
//中间省略业务代码
return NpResult.success();
}
}
第三步:在controller中用到的自定义对象都需要加上swagger注解逐个说明
NpResult 这个实体类是自己封装使用的数据返回对象
/**
* author: 聂鹏
* email:122352701@qq.com
* description: 带 swagger 接口文档的数据返回格式
* create:2019/8/25
*/
@Data
@ApiModel(description = "响应的json对象")
public class NpResult implements Serializable {
@ApiModelProperty(value="返回的文本信息",required=true)
private String msg;
@ApiModelProperty(value="返回布尔值表示请求成功/失败!",required=true)
private boolean result;
@ApiModelProperty(value="分页时返回总条数")
private Long count;
@ApiModelProperty(value="返回的数据对象")
private Object data;
@ApiModelProperty(value="其他数据")
private Object obj;
private NpResult(String msg, boolean result, Long count, Object data, Object obj) {
this.msg = msg;
this.result = result;
this.count = count;
this.data = data;
this.obj = obj;
}
public static NpResult success() {
return new NpResult("操作成功",true,null,null,null);
}
public static NpResult success(Object data) {
return new NpResult("操作成功",true,null,data,null);
}
/** 返回多个对象 */
public static NpResult success(Object data,Object obj) {
return new NpResult("操作成功",true,null,data,obj);
}
/** layui分页返回 */
public static NpResult success(Long count,Object data) {
return new NpResult("操作成功",true,count,data,null);
}
public static NpResult success(Long count,Object data,Object obj) {
return new NpResult("操作成功",true,count,data,obj);
}
public static NpResult error() {
return new NpResult("操作失败",false,null,null,null);
}
public static NpResult error(String msg) {
return new NpResult(msg,false,null,null,null);
}
public static NpResult error(String msg,Object data) {
return new NpResult(msg,false,null,data,null);
}
CountParam 上面controller用到的用来接收参数的对象说明
/**
* author: 聂鹏
* email:122352701@qq.com
* description: 参数对象
* create:2019/8/25
*/
@Data
@ApiModel(description = "请求参数对象")
public class CountParam {
@ApiModelProperty(value="实际公里数:单位公里",required=true,example="50")
private double km;
@ApiModelProperty(value="开始时间,格式yyyy-MM-dd HH:mm:ss",required=true,example="2019-07-17 19:00:00")
private String beginDate;
@ApiModelProperty(value="结束时间,格式yyyy-MM-dd HH:mm:ss",required=true,example="2019-07-17 19:10:00")
private String endDate;
@ApiModelProperty(value="低速行驶时间:单位分钟",example = "10")
private int underspeedTime;
@ApiModelProperty(value="优惠券:单位元",example = "10")
private double coupon;
}
第四步:在application.properties里面加上API说明
spring.swagger.title=计费系统
spring.swagger.description=计费系统接口文档
spring.swagger.version=1.0
spring.swagger.contact.name=聂鹏
spring.swagger.contact.email=122352701@qq.com
spring.swagger.base-package=com.xxxxx.carfee.controller
第5步:在springboot的启动类上加上注解就可以了
@EnableSwagger2
@SpringBootApplication
public class CarfeeApplication {
public static void main(String[] args) {
SpringApplication.run(CarfeeApplication.class, args);
}
}
在线接口文档地址: xxxx/swagger-ui.html
我的是 http://localhost:8081/carfee/swagger-ui.html
最后附上使用后的效果
刚进入的总览:
点击测试接口可以看到接口说明, 如果有参数可以看到参数说明
点击NpResult可以看到返回的对象说明
还可以在线调试, postman都可以不用了, 给前端人员做对接调试非常方便
在线接口文档完成, 下一篇记录导出在线文档为离线的html和PDF