目录
一、订单系统接口
1.1 Swagger-UI
1.1.1 什么是OpenApi
随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、前后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。 前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要。
没有API文档工具之前,大家都是手写API文档的,在什么地方书写的都有,而且API文档没有统一规范和格式,每个公司都不一样。这无疑给开发带来了灾难。
OpenAPI规范(OpenAPI Specification 简称OAS)是Linux基金会的一个项目,试图通过定义一种用来描述API格式或API定义的语言,来规范RESTful服务开发过程。目前V3.0版本的OpenAPI规范已经发布并开源在github上 。
官网:https://github.com/OAI/OpenAPI-Specification
1.1.2 什么是Swagger
OpenAPI是一个编写API文档的规范,然而如果手动去编写OpenAPI规范的文档,是非常麻烦的。而Swagger就是一个实现了OpenAPI规范的工具集。
官方的说明:
Swagger包含的工具集:
-
Swagger编辑器: Swagger Editor允许您在浏览器中编辑YAML中的OpenAPI规范并实时预览文档。
-
Swagger UI: Swagger UI是HTML,Javascript和CSS资产的集合,可以从符合OAS标准的API动态生成漂亮的文档。
-
Swagger Codegen:允许根据OpenAPI规范自动生成API客户端库(SDK生成),服务器存根和文档。
-
Swagger Parser:用于解析来自Java的OpenAPI定义的独立库
-
Swagger Core:与Java相关的库,用于创建,使用和使用OpenAPI定义
-
Swagger Inspector(免费): API测试工具,可让您验证您的API并从现有API生成OpenAPI定义
-
SwaggerHub(免费和商业): API设计和文档,为使用OpenAPI的团队构建。
1.1.3 快速入门
SpringBoot已经集成了Swagger,使用简单注解即可生成swagger的API文档。
引入依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
编写配置
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.host("http://order.leyou.com")
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.leyou.order.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("乐优商城订单系统")
.description("乐优商城订单系统接口文档")
.version("1.0")
.build();
}
}
接口声明
在controller的每个handler上添加接口说明注解:
package com.leyou.order.controller;
import com.leyou.common.pojo.PageResult;
import com.leyou.order.pojo.Order;
import com.leyou.order.service.OrderService;
import com.leyou.order.utils.PayHelper;
import com.leyou.order.utils.PayState;
import io.swagger.annotations.*;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import javax.validation.Valid;
/**
* @Author: 98050
* @Time: 2018-10-27 16:30
* @Feature: 订单Controller
*/
@RestController
@Api("订单服务接口")
public class OrderController {
@Autowired
private OrderService orderService;
@Autowired
private PayHelper payHelper;
/**
* 创建订单
* @param order 订单对象
* @return 订单编号
*/
@PostMapping
@ApiOperation(value = "创建订单接口,返回订单编号",notes = "创建订单")
@ApiImplicitParam(name = "order",required = true,value = "订单的json对象,包含订单条目和物流信息")
public ResponseEntity<Long> createOrder(@RequestBody @Valid Order order){
Long id = this.orderService.createOrder(order);
return new ResponseEntity<>(id, HttpStatus.CREATED);
}
/**
* 查询订单
* @param id 订单编号
* @return 订单对象
*/
@ApiOperation(value = "根据订单编号查询订单,返回订单对象",notes = "查询订单")
@ApiImplicitParam(name = "id",required = true,value = "订单编号")
@GetMapping("{id}")
public ResponseEntity<Order> queryOrderById(@PathVariable("id") Long id){
Order order = this.orderService.queryOrderById(id);
if (order == null){
return ResponseEntity.status(HttpStatus.NOT_FOUND).build();
}
return ResponseEntity.ok(order);
}
/**
* 分页查询当前已经登录的用户订单
* @param page 页数
* @param rows 每页大小
* @param status 订单状态
* @return
*/
@GetMapping("list")
@ApiOperation(value = "分页查询当前用户订单,并且可以根据订单状态过滤",notes = "分页查询当前用户订单")
@ApiImplicitParams({
@ApiImplicitParam(name = "page",value = "当前页",defaultValue = "1",type = "Integer"),
@ApiImplicitParam(name = "rows",value = "每页大小",defaultValue = "5",type = "Integer"),
@ApiImplicitParam(name = "status",value = "订单状态:1未付款," +
"2已付款未发货," +
"3已发货未确认," +
"4已确认未评价," +
"5交易关闭," +
"6交易成功,已评价",defaultValue = "1",type = "Integer")
})
@ApiResponses({
@ApiResponse(code = 200, message = "订单的分页结果"),
@ApiResponse(code = 404, message = "没有查询到结果"),
@ApiResponse(code = 500,message = "服务器异常")
})
public ResponseEntity<PageResult<Order>> queryUserOrderList(
@RequestParam(value = "page",defaultValue = "1")Integer page,
@RequestParam(value = "rows",defaultValue = "5")Integer rows,
@RequestParam(value = "status",required = false)Integer status
){
PageResult<Order> result = this.orderService.queryUserOrderList(page,rows,status);
if (result == null){
return new ResponseEntity<>(HttpStatus.NOT_FOUND);
}
return ResponseEntity.ok(result);
}
/**
* 更新订单状态
* @param id
* @param status
* @return
*/
@PutMapping("{id}/{status}")
@ApiOperation(value = "更新订单状态",notes = "更新订单状态")
@ApiImplicitParams({
@ApiImplicitParam(name = "id",value = "订单编号",type = "Long"),
@ApiImplicitParam(name = "status",value = "订单状态:1未付款," +
"2已付款未发货," +
"3已发货未确认," +
"4已确认未评价," +
"5交易关闭," +
"6交易成功,已评价",defaultValue = "1",type = "Integer")
})
@ApiResponses({
@ApiResponse(code = 204,message = "true:修改成功;false:修改状态失败"),
@ApiResponse(code = 400,message = "请求参数有误"),
@ApiResponse(code = 500,message = "服务器异常")
})
public ResponseEntity<Boolean> updateOrderStatus(@PathVariable("id") Long id,@PathVariable("status") Integer status){
Boolean result = this.orderService.updateOrderStatus(id,status);
if (result == null){
//返回400
return new ResponseEntity<>(HttpStatus.BAD_REQUEST);
}
//返回204
return new ResponseEntity<>(result,HttpStatus.NO_CONTENT);
}
/**
* 根据订单id生成付款链接
* @param orderId
* @return
*/
@GetMapping("url/{id}")
@ApiOperation(value = "生成微信扫描支付付款链接",notes = "生成付款链接")
@ApiImplicitParam(name = "id",value = "订单编号",type = "Long")
@ApiResponses({
@ApiResponse(code = 200,message = "根据订单编号生成的微信支付地址"),
@ApiResponse(code = 404,message = "生成链接失败"),
@ApiResponse(code = 500,message = "服务器异常")
})
public ResponseEntity<String> generateUrl(@PathVariable("id") Long orderId){
String url = this.payHelper.createPayUrl(orderId);
if (StringUtils.isNotBlank(url)){
return ResponseEntity.ok(url);
}else {
return ResponseEntity.status(HttpStatus.NOT_FOUND).build();
}
}
/**
* 查询付款状态
* @param orderId
* @return
*/
@GetMapping("state/{id}")
@ApiOperation(value = "查询扫码支付的付款状态",notes = "查询付款状态")
@ApiImplicitParam(name = "id",value = "订单编号",type = "Long")
@ApiResponses({
@ApiResponse(code = 200, message = "0, 未查询到支付信息 1,支付成功 2,支付失败"),
@ApiResponse(code = 500, message = "服务器异常"),
})
public ResponseEntity<Integer> queryPayState(@PathVariable("id") Long orderId){
PayState payState = this.payHelper.queryOrder(orderId);
return ResponseEntity.ok(payState.getValue());
}
}
常用注解说明:
/**
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数
*/
启动测试
启动服务,然后访问:http://localhost:8089/swagger-ui.html
访问过程中遇到到错误请参考:《坑》
点击order-controller,查看接口信息
点击任意一个接口,即可查看详细信息:
1.2 测试接口
1.2.1 创建订单接口
可以通过页面看到接口信息:
-
请求方式:POST
-
请求路径:/order
-
请求参数:包含订单、订单详情等数据的json对象。
-
返回结果:订单编号
点击
Try It Out
来测试
填入数据
{
"totalPay": 236800,
"postFee": 0,
"paymentType": 2,
"actualPay": 236800,
"buyerMessage": null,
"buyerNick": "huge",
"orderDetails": [
{
"skuId": 3893493,
"num": 1,
"title": "苹果(Apple)iPhone 6 (A1586) 16GB 金色 移动联通电信4G手机3",
"price": 236800,
"ownSpec": "{\"机身颜色\":\"钻雕蓝\",\"内存\":\"4GB\",\"机身存储\":\"64GB\"}",
"image": "http://image.leyou.com/images/9/4/1524297342728.jpg"
}
],
"receiver": "锋哥",
"receiverMobile": "15800000000",
"receiverState": "上海",
"receiverCity": "上海",
"receiverDistrict": "浦东新签",
"receiverAddress": "航头镇航头路18号传智播客3号楼",
"receiverZip": "210000",
"invoiceType": 0,
"sourceType":2
}
点击Execute
查看返回结果
401 未授权,因为下订单需要用户登录,所以要携带token。
通过登录生成token
把token的值手动加入到浏览器的cookie中
再次执行
添加成功,响应订单编号。
1.2.2 生成ID方式
请参考:《分布式自增id》
1.2.3 查询订单接口
接口说明
-
请求方式:GET
-
请求路径:/order/{id}
-
请求参数:id,订单编号
-
返回结果:Order,订单的json对象
测试
输入刚才生成的订单号:
结果:
1.2.4 更新订单状态
接口说明
-
请求参数:PUT
-
请求路径:/order/{id}/{status}
-
请求参数:
-
id:订单编号,String类型,不能为空
-
status:订单状态,不能为空
-
-
返回结果:null
测试
数据库中的数据:
修改:
结果:
数据库:
1.2.5 分页查询订单
接口说明
-
请求方式:Get
-
请求路径:/order/list
-
请求参数:
-
page:当前页,Integer类型,默认为1
-
rows:每页大小,Integer类型,默认为5
-
status:订单状态,String类型,默认查询全部状态订单
-
-
返回结果:PageResult 对象,包含下面属性:
-
total:总条数
-
items:当前页订单数组
-
订单对象
-
-
测试
结果:
改造一下分页代码
1.2.6 生成微信付款链接
接口说明
-
请求方式:Get
-
请求路径:/order/url/{id}
-
请求参数:id,订单编号
-
返回结果:String类型,生成的微信支付链接
测试
结果:
1.2.7 查询支付状态
接口说明
-
请求方式: Get
-
请求路径: /state/{id}
-
请求参数: id,订单编号
-
返回结果:0, 未查询到支付信息 1,支付成功 2,支付失败(查询失败,或者订单过期)
未付款
未付款时查询,测试:
结果:
付款
已付款