update[litemall-wx-api]: 添加方法注释和检验方法参数

litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxAddressController.java

@@ -8,10 +8,7 @@ import org.linlinjava.litemall.db.service.LitemallRegionService;
 import org.linlinjava.litemall.db.util.ResponseUtil;
 import org.linlinjava.litemall.wx.annotation.LoginUser;
 import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.web.bind.annotation.PostMapping;
-import org.springframework.web.bind.annotation.RequestBody;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.bind.annotation.*;
 
 import java.util.ArrayList;
 import java.util.HashMap;
@@ -27,13 +24,24 @@ public class WxAddressController {
     private LitemallAddressService addressService;
     @Autowired
     private LitemallRegionService regionService;
+
     /**
-     * 获取用户的收货地址
+     * 用户收货地址列表
+     *
+     * @param userId 用户ID
+     * @return 收货地址列表
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data: xxx
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("list")
+    @GetMapping("list")
     public Object list(@LoginUser Integer userId) {
         if(userId == null){
-            return ResponseUtil.fail401();
+            return ResponseUtil.unlogin();
         }
         List<LitemallAddress> addressList = addressService.queryByUid(userId);
         List<Map<String, Object>> addressVoList = new ArrayList<>(addressList.size());
@@ -56,9 +64,33 @@ public class WxAddressController {
     }
 
     /**
-     * 获取收货地址的详情
+     * 收货地址详情
+     *
+     * @param userId 用户ID
+     * @param id 收获地址ID
+     * @return 收货地址详情
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *        {
+     *           id: xxx,
+     *           name: xxx,
+     *           provinceId: xxx,
+     *           cityId: xxx,
+     *           districtId: xxx,
+     *           mobile: xxx,
+     *           address: xxx,
+     *           isDefault: xxx,
+     *           provinceName: xxx,
+     *           cityName: xxx,
+     *           areaName: xxx
+     *        }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("detail")
+    @GetMapping("detail")
     public Object detail(@LoginUser Integer userId, Integer id) {
         if(userId == null){
             return ResponseUtil.fail401();
@@ -92,6 +124,12 @@ public class WxAddressController {
 
     /**
      * 添加或更新收货地址
+     *
+     * @param userId 用户ID
+     * @param address 用户收货地址
+     * @return 添加或更新操作结果
+     *   成功则 { errno: 0, errmsg: '成功' }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
     @PostMapping("save")
     public Object save(@LoginUser Integer userId, @RequestBody LitemallAddress address) {
@@ -107,7 +145,7 @@ public class WxAddressController {
             addressService.resetDefault(userId);
         }
 
-        if (address.getId() == null || address.getId() == 0) {
+        if (address.getId() == null || address.getId().equals(0)) {
             address.setId(null);
             address.setUserId(userId);
             addressService.add(address);
@@ -119,9 +157,15 @@ public class WxAddressController {
     }
 
     /**
-     * 删除指定的收货地址
+     * 删除收货地址
+     *
+     * @param userId 用户ID
+     * @param address 用户收货地址
+     * @return 删除结果
+     *   成功则 { errno: 0, errmsg: '成功' }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("delete")
+    @PostMapping("delete")
     public Object delete(@LoginUser Integer userId, @RequestBody LitemallAddress address) {
         if(userId == null){
             return ResponseUtil.fail401();

litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxAuthController.java

@@ -41,6 +41,22 @@ public class WxAuthController {
 
     /**
      * 账号登录
+     *
+     * @param body 请求内容，{ username: xxx, password: xxx }
+     * @param request 请求对象
+     * @return 登录结果
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              token: xxx,
+     *              tokenExpire: xxx,
+     *              userInfo: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
     @RequestMapping("login")
     public Object login(@RequestBody String body, HttpServletRequest request) {
@@ -84,6 +100,22 @@ public class WxAuthController {
 
     /**
      * 微信登录
+     *
+     * @param body 请求内容，{ code: xxx, userInfo: xxx }
+     * @param request 请求对象
+     * @return 登录结果
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              token: xxx,
+     *              tokenExpire: xxx,
+     *              userInfo: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
     @RequestMapping("login_by_weixin")
     public Object loginByWeixin(@RequestBody String body, HttpServletRequest request) {
@@ -150,6 +182,29 @@ public class WxAuthController {
 
     /**
      * 账号注册
+     *
+     * @param body 请求内容
+     *  {
+     *      username: xxx,
+     *      password: xxx,
+     *      mobile: xxx
+     *      code: xxx
+     *  }
+     *  其中code是手机验证码，目前还不支持手机短信验证码
+     * @param request 请求对象
+     * @return 登录结果
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              token: xxx,
+     *              tokenExpire: xxx,
+     *              userInfo: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
     @PostMapping("register")
     public Object register(@RequestBody String body, HttpServletRequest request) {
@@ -209,6 +264,18 @@ public class WxAuthController {
 
     /**
      * 账号密码重置
+     *
+     * @param body 请求内容
+     *  {
+     *      password: xxx,
+     *      mobile: xxx
+     *      code: xxx
+     *  }
+     *  其中code是手机验证码，目前还不支持手机短信验证码
+     * @param request 请求对象
+     * @return 登录结果
+     *   成功则 { errno: 0, errmsg: '成功' }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
     @PostMapping("reset")
     public Object reset(@RequestBody String body, HttpServletRequest request) {

litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxBrandController.java

@@ -6,6 +6,7 @@ import org.linlinjava.litemall.db.domain.LitemallBrand;
 import org.linlinjava.litemall.db.service.LitemallBrandService;
 import org.linlinjava.litemall.db.util.ResponseUtil;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
@@ -23,9 +24,24 @@ public class WxBrandController {
     private LitemallBrandService brandService;
 
     /**
-     * 分页获取品牌
+     * 品牌列表
+     *
+     * @param page 分页页数
+     * @param size 分页大小
+     * @return 品牌列表
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              brandList: xxx,
+     *              totalPages: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("list")
+    @GetMapping("list")
     public Object list(@RequestParam(value = "page", defaultValue = "1") Integer page,
                        @RequestParam(value = "size", defaultValue = "10") Integer size) {
 
@@ -41,18 +57,31 @@ public class WxBrandController {
 
     /**
      * 品牌详情
+     *
+     * @param id 品牌ID
+     * @return 品牌详情
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              brand: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("detail")
+    @GetMapping("detail")
     public Object detail(Integer id) {
         if(id == null){
-            return ResponseUtil.fail402();
+            return ResponseUtil.badArgument();
         }
 
         LitemallBrand entity = brandService.findById(id);
-
         if(entity == null){
-            return ResponseUtil.fail403();
+            return ResponseUtil.badArgumentValue();
         }
+
         Map<String, Object> data = new HashMap();
         data.put("brand",entity);
         return ResponseUtil.ok(data);

litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxCartController.java

@@ -1,5 +1,6 @@
 package org.linlinjava.litemall.wx.web;
 
+import org.apache.commons.lang3.ObjectUtils;
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 import org.linlinjava.litemall.db.domain.*;
@@ -8,9 +9,7 @@ import org.linlinjava.litemall.db.util.JacksonUtil;
 import org.linlinjava.litemall.db.util.ResponseUtil;
 import org.linlinjava.litemall.wx.annotation.LoginUser;
 import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.web.bind.annotation.RequestBody;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.bind.annotation.*;
 
 import java.math.BigDecimal;
 import java.util.ArrayList;
@@ -35,13 +34,28 @@ public class WxCartController {
     private LitemallAddressService addressService;
     @Autowired
     private LitemallCouponService apiCouponService;
+
     /**
-     * 获取购物车
+     * 购物车
+     *
+     * @param userId 用户ID
+     * @return 购物车
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              cartList: xxx,
+     *              cartTotal: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("index")
+    @GetMapping("index")
     public Object index(@LoginUser Integer userId) {
         if(userId == null){
-            return ResponseUtil.fail(401, "请登录");
+            return ResponseUtil.unlogin();
         }
         
         List<LitemallCart> cartList = cartService.queryByUid(userId);
@@ -72,8 +86,21 @@ public class WxCartController {
 
     /**
      * 添加商品加入购物车
+     * 如果已经存在购物车货品，则添加数量；
+     * 否则添加新的购物车货品项。
+     *
+     * @param userId 用户ID
+     * @param cart 购物车商品信息， { goodsId: xxx, productId: xxx, number: xxx }
+     * @return 加入购物车操作结果
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data: xxx
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("add")
+    @PostMapping("add")
     public Object add(@LoginUser Integer userId, @RequestBody LitemallCart cart) {
         if(userId == null){
             return ResponseUtil.unlogin();
@@ -85,6 +112,9 @@ public class WxCartController {
         Integer productId = cart.getProductId();
         Integer number = cart.getNumber().intValue();
         Integer goodsId = cart.getGoodsId();
+        if(!ObjectUtils.allNotNull(productId, number, goodsId)){
+            return ResponseUtil.badArgument();
+        }
 
         //判断商品是否可以购买
         LitemallGoods goods = goodsService.findById(goodsId);
@@ -102,17 +132,17 @@ public class WxCartController {
             }
 
             Integer[] ids = product.getGoodsSpecificationIds();
-            String goodsSepcifitionValue = null;
+            String goodsSpecificationValue = null;
             for(Integer id : ids){
                 LitemallGoodsSpecification goodsSpecification = goodsSpecificationService.findById(id);
                 if(goodsSpecification == null || !goodsSpecification.getGoodsId().equals(goodsId)){
                     return ResponseUtil.badArgument();
                 }
-                if(goodsSepcifitionValue == null){
-                    goodsSepcifitionValue = goodsSpecification.getValue();
+                if(goodsSpecificationValue == null){
+                    goodsSpecificationValue = goodsSpecification.getValue();
                 }
                 else {
-                    goodsSepcifitionValue = goodsSepcifitionValue + " " + goodsSpecification.getValue();
+                    goodsSpecificationValue = goodsSpecificationValue + " " + goodsSpecification.getValue();
                 }
             }
 
@@ -122,7 +152,7 @@ public class WxCartController {
             cart.setPicUrl(goods.getPrimaryPicUrl());
             cart.setRetailPrice(product.getRetailPrice());
             cart.setGoodsSpecificationIds(product.getGoodsSpecificationIds());
-            cart.setGoodsSpecificationValues(goodsSepcifitionValue);
+            cart.setGoodsSpecificationValues(goodsSpecificationValue);
             cart.setUserId(userId);
             cart.setChecked(true);
             cartService.add(cart);
@@ -144,10 +174,21 @@ public class WxCartController {
      * 立即购买商品
      *
      * 和 前面一个方法add的区别在于
-     * 1. 如果购物车内有相同商品存在，前者的逻辑是数量添加，这里的逻辑是数量覆盖
+     * 1. 如果购物车内已经存在购物车货品，前者的逻辑是数量添加，这里的逻辑是数量覆盖
      * 2. 添加成功以后，前者的逻辑是返回当前购物车商品数量，这里的逻辑是返回对应购物车项的ID
+     *
+     * @param userId 用户ID
+     * @param cart 购物车商品信息， { goodsId: xxx, productId: xxx, number: xxx }
+     * @return 即购买操作结果
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data: xxx
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("fastadd")
+    @PostMapping("fastadd")
     public Object fastadd(@LoginUser Integer userId, @RequestBody LitemallCart cart) {
         if(userId == null){
             return ResponseUtil.unlogin();
@@ -159,6 +200,9 @@ public class WxCartController {
         Integer productId = cart.getProductId();
         Integer number = cart.getNumber().intValue();
         Integer goodsId = cart.getGoodsId();
+        if(!ObjectUtils.allNotNull(productId, number, goodsId)){
+            return ResponseUtil.badArgument();
+        }
 
         //判断商品是否可以购买
         LitemallGoods goods = goodsService.findById(goodsId);
@@ -176,17 +220,17 @@ public class WxCartController {
             }
 
             Integer[] ids = product.getGoodsSpecificationIds();
-            String goodsSepcifitionValue = null;
+            String goodsSpecificationValue = null;
             for(Integer id : ids){
                 LitemallGoodsSpecification goodsSpecification = goodsSpecificationService.findById(id);
                 if(goodsSpecification == null || !goodsSpecification.getGoodsId().equals(goodsId)){
                     return ResponseUtil.badArgument();
                 }
-                if(goodsSepcifitionValue == null){
-                    goodsSepcifitionValue = goodsSpecification.getValue();
+                if(goodsSpecificationValue == null){
+                    goodsSpecificationValue = goodsSpecification.getValue();
                 }
                 else {
-                    goodsSepcifitionValue = goodsSepcifitionValue + " " + goodsSpecification.getValue();
+                    goodsSpecificationValue = goodsSpecificationValue + " " + goodsSpecification.getValue();
                 }
             }
 
@@ -196,7 +240,7 @@ public class WxCartController {
             cart.setPicUrl(goods.getPrimaryPicUrl());
             cart.setRetailPrice(product.getRetailPrice());
             cart.setGoodsSpecificationIds(product.getGoodsSpecificationIds());
-            cart.setGoodsSpecificationValues(goodsSepcifitionValue);
+            cart.setGoodsSpecificationValues(goodsSpecificationValue);
             cart.setUserId(userId);
             cart.setChecked(true);
             cartService.add(cart);
@@ -217,34 +261,42 @@ public class WxCartController {
     /**
      * 更新指定的购物车信息
      * 目前只支持修改商品的数量
+     *
+     * @param userId 用户ID
+     * @param cart 购物车商品信息， { id: xxx, goodsId: xxx, productId: xxx, number: xxx }
+     * @return 更新购物车操作结果
+     *   成功则 { errno: 0, errmsg: '成功' }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("update")
+    @PostMapping("update")
     public Object update(@LoginUser Integer userId, @RequestBody LitemallCart cart) {
         if(userId == null){
-            return ResponseUtil.fail401();
+            return ResponseUtil.unlogin();
         }
         if(cart == null){
-            return ResponseUtil.fail402();
+            return ResponseUtil.badArgument();
         }
-        
         Integer productId = cart.getProductId();
         Integer number = cart.getNumber().intValue();
         Integer goodsId = cart.getGoodsId();
         Integer id = cart.getId();
+        if(!ObjectUtils.allNotNull(id, productId, number, goodsId)){
+            return ResponseUtil.badArgument();
+        }
 
         //判断是否存在该订单
         // 如果不存在，直接返回错误
         LitemallCart existCart = cartService.findById(id);
         if(existCart == null){
-            return ResponseUtil.fail403();
+            return ResponseUtil.badArgumentValue();
         }
 
         // 判断goodsId和productId是否与当前cart里的值一致
         if(!existCart.getGoodsId().equals(goodsId)){
-            return ResponseUtil.fail403();
+            return ResponseUtil.badArgumentValue();
         }
         if(!existCart.getProductId().equals(productId)){
-            return ResponseUtil.fail403();
+            return ResponseUtil.badArgumentValue();
         }
 
         //判断商品是否可以购买
@@ -265,24 +317,37 @@ public class WxCartController {
     }
 
     /**
-     * 是否选择商品，如果已经选择，则取消选择，批量操作
+     * 购物车商品勾选
+     * 如果原来没有勾选，则设置勾选状态；如果商品已经勾选，则设置非勾选状态。
+     *
+     * @param userId 用户ID
+     * @param body 购物车商品信息， { productIds: xxx }
+     * @return 购物车信息
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data: xxx
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("checked")
+    @PostMapping("checked")
     public Object checked(@LoginUser Integer userId, @RequestBody String body) {
         if(userId == null){
-            return ResponseUtil.fail401();
+            return ResponseUtil.unlogin();
         }
         if(body == null){
-            return ResponseUtil.fail402();
+            return ResponseUtil.badArgument();
         }
         
         List<Integer> productIds = JacksonUtil.parseIntegerList(body, "productIds");
         if(productIds == null){
-            return ResponseUtil.fail402();
+            return ResponseUtil.badArgument();
         }
+
         Integer checkValue = JacksonUtil.parseInteger(body, "isChecked");
         if(checkValue == null){
-            return ResponseUtil.fail402();
+            return ResponseUtil.badArgument();
         }
         Boolean isChecked = ((checkValue.intValue()) == 1);
 
@@ -290,29 +355,53 @@ public class WxCartController {
         return index(userId);
     }
 
-    //删除选中的购物车商品，批量删除
-    @RequestMapping("delete")
+    /**
+     * 购物车商品删除
+     * 如果原来没有勾选，则设置勾选状态；如果商品已经勾选，则设置非勾选状态。
+     *
+     * @param userId 用户ID
+     * @param body 购物车商品信息， { productIds: xxx }
+     * @return 购物车信息
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data: xxx
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
+     */
+    @PostMapping("delete")
     public Object delete(@LoginUser Integer userId, @RequestBody String body) {
         if(userId == null){
-            return ResponseUtil.fail401();
+            return ResponseUtil.unlogin();
         }
         if(body == null){
-            return ResponseUtil.fail402();
+            return ResponseUtil.badArgument();
         }
         
         List<Integer> productIds = JacksonUtil.parseIntegerList(body, "productIds");
 
         if(productIds == null){
-            return ResponseUtil.fail402();
+            return ResponseUtil.badArgument();
         }
 
         cartService.delete(productIds, 1);
         return index(userId);
     }
 
-    /*
-     * 获取购物车商品的总件件数
-     * 用户也是可选登录，如果没有登录，则返回空数据
+    /**
+     * 购物车商品数量
+     * 如果用户没有登录，则返回空数据。
+     *
+     * @param userId 用户ID
+     * @return 购物车商品数量
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data: xxx
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
     @RequestMapping("goodscount")
     public Object goodscount(@LoginUser Integer userId) {
@@ -330,12 +419,41 @@ public class WxCartController {
     }
 
     /**
-     * 订单提交前的检验和填写相关订单信息
+     * 购物车下单信息
+     *
+     * @param userId 用户ID
+     * @param cartId 购物车商品ID
+     *    如果购物车商品ID是空，则下单当前用户所有购物车商品；
+     *    如果购物车商品ID非空，则只下单当前购物车商品。
+     * @param addressId 收货地址ID
+     *    如果收货地址ID是空，则查询当前用户的默认地址。
+     * @param couponId 优惠券ID
+     *    目前不支持
+     * @return 购物车下单信息
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *      {
+     *          addressId: xxx,
+     *          checkedAddress: xxx,
+     *          couponId: xxx,
+     *          checkedCoupon: xxx,
+     *          goodsTotalPrice: xxx,
+     *          freightPrice: xxx,
+     *          couponPrice: xxx,
+     *          orderTotalPrice: xxx,
+     *          actualPrice: xxx,
+     *          checkedGoodsList: xxx
+     *      }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("checkout")
+    @GetMapping("checkout")
     public Object checkout(@LoginUser Integer userId, Integer cartId, Integer addressId, Integer couponId) {
         if(userId == null){
-            return ResponseUtil.fail401();
+            return ResponseUtil.unlogin();
         }
 
         // 收货地址
@@ -398,29 +516,38 @@ public class WxCartController {
         BigDecimal actualPrice = orderTotalPrice.subtract(integralPrice);
 
         Map<String, Object> data = new HashMap();
+        data.put("addressId", addressId);
         data.put("checkedAddress", checkedAddress);
-        data.put("freightPrice", freightPrice);
+        data.put("couponId", couponId);
         data.put("checkedCoupon", 0);
-        data.put("couponList", "");
-        data.put("couponPrice", couponPrice);
-        data.put("checkedGoodsList", checkedGoodsList);
         data.put("goodsTotalPrice", checkedGoodsPrice);
+        data.put("freightPrice", freightPrice);
+        data.put("couponPrice", couponPrice);
         data.put("orderTotalPrice", orderTotalPrice);
         data.put("actualPrice", actualPrice);
-        data.put("addressId", addressId);
-        data.put("couponId", couponId);
+        data.put("checkedGoodsList", checkedGoodsList);
         return ResponseUtil.ok(data);
-
     }
 
     /**
-     * 选择优惠券列表
+     * 商品优惠券列表
+     * 目前不支持
+     *
+     * @param userId 用户ID
+     * @return 商品优惠券信息
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data: xxx
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("checkedCouponList")
+    @GetMapping("checkedCouponList")
     public Object checkedCouponList(@LoginUser Integer userId) {
         if(userId == null){
-            return ResponseUtil.fail401();
+            return ResponseUtil.unlogin();
         }
-        return ResponseUtil.fail501();
+        return ResponseUtil.unsupport();
     }
 }

litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxCatalogController.java

@@ -4,6 +4,7 @@ import org.linlinjava.litemall.db.domain.LitemallCategory;
 import org.linlinjava.litemall.db.service.LitemallCategoryService;
 import org.linlinjava.litemall.db.util.ResponseUtil;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
@@ -19,11 +20,28 @@ public class WxCatalogController {
     private LitemallCategoryService categoryService;
 
     /**
-     * 获取分类栏目数据
-     * 参数id是可选的，如果没有设置，则选择第一个一级目录
-     * 这里的id应该是一级目录的id。
+     * 分类栏目
+     *
+     * @param id 分类类目ID
+     *    如果分类类目ID是空，则选择第一个分类类目。
+     *    需要注意，这里分类类目是一级类目
+     * @param page 分页页数
+     * @param size 分页大小
+     * @return 分类栏目
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              categoryList: xxx,
+     *              currentCategory: xxx,
+     *              currentSubCategory: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("index")
+    @GetMapping("index")
     public Object index(Integer id,
                         @RequestParam(value = "page", defaultValue = "1") Integer page,
                         @RequestParam(value = "size", defaultValue = "10") Integer size) {
@@ -54,12 +72,26 @@ public class WxCatalogController {
     }
 
     /**
-     * 这里的参数id是一级目录的id。
+     * 当前分类栏目
+     *
+     * @param id 分类类目ID
+     * @return 当前分类栏目
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              currentCategory: xxx,
+     *              currentSubCategory: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("current")
+    @GetMapping("current")
     public Object current(Integer id) {
         if(id == null){
-            return ResponseUtil.fail402();
+            return ResponseUtil.badArgument();
         }
 
         // 当前分类

litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxCollectController.java

@@ -1,5 +1,6 @@
 package org.linlinjava.litemall.wx.web;
 
+import org.apache.commons.lang3.ObjectUtils;
 import org.linlinjava.litemall.db.domain.LitemallCollect;
 import org.linlinjava.litemall.db.domain.LitemallGoods;
 import org.linlinjava.litemall.db.service.LitemallCollectService;
@@ -8,10 +9,7 @@ import org.linlinjava.litemall.db.util.JacksonUtil;
 import org.linlinjava.litemall.db.util.ResponseUtil;
 import org.linlinjava.litemall.wx.annotation.LoginUser;
 import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.web.bind.annotation.RequestBody;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RequestParam;
-import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.bind.annotation.*;
 
 import java.time.LocalDate;
 import java.time.LocalDateTime;
@@ -29,20 +27,37 @@ public class WxCollectController {
     private LitemallGoodsService goodsService;
 
     /**
-     * 获取用户收藏
+     * 用户收藏列表
+     *
+     * @param userId 用户ID
+     * @param typeId 类型ID
+     *    目前没有使用
+     * @param page 分页页数
+     * @param size 分页大小
+     * @return 用户收藏列表
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              collectList: xxx,
+     *              totalPages: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("list")
+    @GetMapping("list")
     public Object list(@LoginUser Integer userId, Integer typeId,
                        @RequestParam(value = "page", defaultValue = "1") Integer page,
                        @RequestParam(value = "size", defaultValue = "10") Integer size) {
         if(userId == null){
-            return ResponseUtil.fail401();
+            return ResponseUtil.unlogin();
         }
         if(typeId == null){
-            return ResponseUtil.fail402();
+            return ResponseUtil.badArgument();
         }
 
-
         List<LitemallCollect> collectList = collectService.queryByType(userId, typeId, page, size);
         int count = collectService.countByType(userId, typeId);
         int totalPages = (int) Math.ceil((double) count / size);
@@ -70,19 +85,37 @@ public class WxCollectController {
     }
 
     /**
-     * 获取用户收藏
+     * 用户收藏添加或删除
+     *
+     * @param userId 用户ID
+     * @param body 请求内容
+     * @return 操作结果
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              type: xxx,
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("addordelete")
+    @PostMapping("addordelete")
     public Object addordelete(@LoginUser Integer userId, @RequestBody String body) {
         if(userId == null){
-            return ResponseUtil.fail401();
+            return ResponseUtil.unlogin();
         }
         if(body == null){
-            return ResponseUtil.fail402();
+            return ResponseUtil.badArgument();
         }
 
         Integer typeId = JacksonUtil.parseInteger(body, "typeId");
         Integer valueId = JacksonUtil.parseInteger(body, "valueId");
+        if(!ObjectUtils.allNotNull(typeId, valueId)){
+            return ResponseUtil.badArgument();
+        }
+
         LitemallCollect collect = collectService.queryByTypeAndValue(userId, typeId, valueId);
 
         String handleType = null;

litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxCommentController.java

@@ -1,5 +1,6 @@
 package org.linlinjava.litemall.wx.web;
 
+import org.apache.commons.lang3.ObjectUtils;
 import org.linlinjava.litemall.db.domain.LitemallComment;
 import org.linlinjava.litemall.db.service.LitemallCommentService;
 import org.linlinjava.litemall.db.service.LitemallCouponService;
@@ -9,10 +10,7 @@ import org.linlinjava.litemall.wx.annotation.LoginUser;
 import org.linlinjava.litemall.wx.service.UserInfoService;
 import org.linlinjava.litemall.wx.dao.UserInfo;
 import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.web.bind.annotation.RequestBody;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RequestParam;
-import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.bind.annotation.*;
 
 import java.time.LocalDate;
 import java.time.LocalDateTime;
@@ -35,14 +33,29 @@ public class WxCommentController {
 
     /**
      * 发表评论
+     *
+     * TODO, 对于评论，应该检测用户是否有权限评论。
+     * 1. 如果用户没有购买过商品，则不能发表对该商品的评论
+     * 2. 如果用户购买商品后规定时间内没有评论，则过期也不能再评论
+     *
+     * @param userId 用户ID
+     * @param comment 评论内容
+     * @return 发表评论操作结果
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data: xxx
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("post")
+    @PostMapping("post")
     public Object post(@LoginUser Integer userId, @RequestBody LitemallComment comment) {
         if(userId == null){
-            return ResponseUtil.fail401();
+            return ResponseUtil.unlogin();
         }
         if(comment == null){
-            return ResponseUtil.fail402();
+            return ResponseUtil.badArgument();
         }
 
         comment.setAddTime(LocalDateTime.now());
@@ -52,8 +65,24 @@ public class WxCommentController {
     }
 
     /**
+     * 评论数量
+     *
+     * @param typeId 类型ID。 如果是0，则查询商品评论；如果是1，则查询专题评论。
+     * @param valueId 商品或专题ID。如果typeId是0，则是商品ID；如果typeId是1，则是专题ID。
+     * @return 评论数量
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              allCount: xxx,
+     *              hasPicCount: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("count")
+    @GetMapping("count")
     public Object count(Byte typeId, Integer valueId) {
         int allCount = commentService.count(typeId, valueId, 0, 0, 0);
         int hasPicCount = commentService.count(typeId, valueId, 1, 0, 0);
@@ -64,18 +93,32 @@ public class WxCommentController {
     }
 
     /**
-     * @param typeId
-     * @param valueId
-     * @param showType 选择评论的类型 0 全部， 1 只显示图片
-     * @param page
-     * @param size
-     * @return
+     * 评论列表
+     *
+     * @param typeId 类型ID。 如果是0，则查询商品评论；如果是1，则查询专题评论。
+     * @param valueId 商品或专题ID。如果typeId是0，则是商品ID；如果typeId是1，则是专题ID。
+     * @param showType 显示类型。如果是0，则查询全部；如果是1，则查询有图片的评论。
+     * @param page 分页页数
+     * @param size 分页大小
+     * @return 评论列表
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              data: xxx,
+     *              count: xxx，
+     *              currentPage: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("list")
+    @GetMapping("list")
     public Object list(Byte typeId, Integer valueId, Integer showType,
                        @RequestParam(value = "page", defaultValue = "1") Integer page,
                        @RequestParam(value = "size", defaultValue = "10") Integer size) {
-        if(typeId == null || valueId == null || showType == null){
+        if(!ObjectUtils.allNotNull(typeId, valueId, showType)){
             return ResponseUtil.badArgument();
         }
 

litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxFootprintController.java

@@ -8,10 +8,7 @@ import org.linlinjava.litemall.db.util.JacksonUtil;
 import org.linlinjava.litemall.db.util.ResponseUtil;
 import org.linlinjava.litemall.wx.annotation.LoginUser;
 import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.web.bind.annotation.RequestBody;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RequestParam;
-import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.bind.annotation.*;
 
 import java.util.ArrayList;
 import java.util.HashMap;
@@ -27,27 +24,34 @@ public class WxFootprintController {
     private LitemallGoodsService goodsService;
 
     /**
+     * 删除用户足迹
+     *
+     * @param userId 用户ID
+     * @param body 请求内容， { footprintId: xxx }
+     * @return 删除操作结果
+     *   成功则 { errno: 0, errmsg: '成功' }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("delete")
+    @PostMapping("delete")
     public Object delete(@LoginUser Integer userId, @RequestBody String body) {
         if(userId == null){
-            return ResponseUtil.fail401();
+            return ResponseUtil.unlogin();
         }
         if(body == null){
-            return ResponseUtil.fail402();
+            return ResponseUtil.badArgument();
         }
 
         Integer footprintId = JacksonUtil.parseInteger(body, "footprintId");
         if(footprintId == null){
-            return ResponseUtil.fail403();
+            return ResponseUtil.badArgument();
         }
         LitemallFootprint footprint = footprintService.findById(footprintId);
 
         if(footprint == null){
-            return ResponseUtil.fail403();
+            return ResponseUtil.badArgumentValue();
         }
         if(!footprint.getUserId().equals(userId)){
-            return ResponseUtil.fail403();
+            return ResponseUtil.badArgumentValue();
         }
 
         footprintService.deleteById(footprintId);
@@ -55,13 +59,29 @@ public class WxFootprintController {
     }
 
     /**
+     * 用户足迹列表
+     *
+     * @param page 分页页数
+     * @param size 分页大小
+     * @return 用户足迹列表
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              footprintList: xxx,
+     *              totalPages: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("list")
+    @GetMapping("list")
     public Object list(@LoginUser Integer userId,
                        @RequestParam(value = "page", defaultValue = "1") Integer page,
                        @RequestParam(value = "size", defaultValue = "10") Integer size) {
         if(userId == null){
-            return ResponseUtil.fail401();
+            return ResponseUtil.unlogin();
         }
 
         List<LitemallFootprint> footprintList = footprintService.queryByAddTime(userId, page, size);
@@ -85,7 +105,7 @@ public class WxFootprintController {
         }
 
 
-        Map<String, Object> result = new HashMap();
+        Map<String, Object> result = new HashMap<>();
         result.put("footprintList", footprintVoList);
         result.put("totalPages", totalPages);
         return ResponseUtil.ok(result);

litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxGoodsController.java

@@ -9,6 +9,7 @@ import org.linlinjava.litemall.db.util.ResponseUtil;
 import org.linlinjava.litemall.db.util.SortUtil;
 import org.linlinjava.litemall.wx.annotation.LoginUser;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
@@ -55,13 +56,36 @@ public class WxGoodsController {
     private LitemallGoodsSpecificationService goodsSpecificationService;
 
     /**
-     * 商品详情页数据
-     * 用户也是可选登录，如果登录了，则查询是否收藏，以及记录用户的足迹
+     * 商品详情
+     *
+     * 用户可以不登录。
+     * 如果用户登录，则记录用户足迹以及返回用户收藏信息。
+     *
+     * @param userId 用户ID
+     * @param id 商品ID
+     * @return 商品详情
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              info: xxx,
+     *              userHasCollect: xxx,
+     *              issue: xxx,
+     *              comment: xxx,
+     *              specificationList: xxx,
+     *              productList: xxx,
+     *              attribute: xxx,
+     *              brand: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("detail")
+    @GetMapping("detail")
     public Object detail(@LoginUser Integer userId, Integer id) {
         if(id == null){
-            return ResponseUtil.fail402();
+            return ResponseUtil.badArgument();
         }
 
         // 商品信息
@@ -131,12 +155,29 @@ public class WxGoodsController {
     }
 
     /**
-     * 　获取分类下的商品
+     * 商品分类类目
+     *
+     * TODO 可能应该合并到WxCatalogController中
+     *
+     * @param id 分类类目ID
+     * @return 商品分类类目
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              currentCategory: xxx,
+     *              parentCategory: xxx,
+     *              brotherCategory: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("category")
+    @GetMapping("category")
     public Object category(Integer id) {
         if(id == null){
-            return ResponseUtil.fail402();
+            return ResponseUtil.badArgument();
         }
         LitemallCategory cur = categoryService.findById(id);
         LitemallCategory parent = null;
@@ -151,7 +192,7 @@ public class WxGoodsController {
             parent = categoryService.findById(cur.getParentId());
             children = categoryService.queryByPid(cur.getParentId());
         }
-        Map<String, Object> data = new HashMap();
+        Map<String, Object> data = new HashMap<>();
         data.put("currentCategory", cur);
         data.put("parentCategory", parent);
         data.put("brotherCategory", children);
@@ -159,12 +200,36 @@ public class WxGoodsController {
     }
 
     /**
-     * 　　获取商品列表
+     * 根据条件搜素商品
+     *
      * 1. 这里的前五个参数都是可选的，甚至都是空
-     * 2. 用户也是可选登录，如果登录了，则记录用户的搜索关键字
+     * 2. 用户是可选登录，如果登录，则记录用户的搜索关键字
      *
+     * @param categoryId 分类类目ID
+     * @param brandId 品牌商ID
+     * @param keyword 关键字
+     * @param isNew 是否新品
+     * @param isHot 是否热买
+     * @param userId 用户ID
+     * @param page 分页页数
+     * @param size 分页大小
+     * @param sort 排序方式
+     * @param order 排序类型，顺序或者降序
+     * @return 根据条件搜素的商品详情
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              goodsList: xxx,
+     *              filterCategoryList: xxx,
+     *              count: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("list")
+    @GetMapping("list")
     public Object list(Integer categoryId, Integer brandId, String keyword, Integer isNew, Integer isHot,
                        @LoginUser Integer userId,
                        @RequestParam(value = "page", defaultValue = "1") Integer page,
@@ -194,7 +259,7 @@ public class WxGoodsController {
             categoryList = categoryService.queryL2ByIds(goodsCatIds);
         }
 
-        Map<String, Object> data = new HashMap();
+        Map<String, Object> data = new HashMap<>();
         data.put("goodsList", goodsList);
         data.put("filterCategoryList", categoryList);
         data.put("count", total);
@@ -202,60 +267,118 @@ public class WxGoodsController {
     }
 
     /**
-     * 　　新品首发
+     * 新品首发页面的横幅数据
+     *
+     * TODO 其实可以删除
+     *
+     * @return 新品首发页面的栏目数据
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              bannerInfo: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("new")
+    @GetMapping("new")
     public Object newGoods() {
-        Map bannerInfo = new HashMap();
+        Map<String, String> bannerInfo = new HashMap<>();
         bannerInfo.put("url", "");
         bannerInfo.put("name", "坚持初心，为你寻觅世间好物");
         bannerInfo.put("imgUrl", "http://yanxuan.nosdn.127.net/8976116db321744084774643a933c5ce.png");
-        Map<String, Object> data = new HashMap();
+
+        Map<String, Object> data = new HashMap<>();
         data.put("bannerInfo", bannerInfo);
         return ResponseUtil.ok(data);
     }
 
     /**
-     * 　　人气推荐
+     * 人气推荐页面的横幅数据
+     *
+     * TODO 其实可以删除
+     *
+     * @return 人气推荐页面的栏目数据
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              bannerInfo: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("hot")
+    @GetMapping("hot")
     public Object hotGoods() {
-        Map bannerInfo = new HashMap();
+        Map<String, String> bannerInfo = new HashMap<>();
         bannerInfo.put("url", "");
         bannerInfo.put("name", "大家都在买的严选好物");
         bannerInfo.put("imgUrl", "http://yanxuan.nosdn.127.net/8976116db321744084774643a933c5ce.png");
-        Map<String, Object> data = new HashMap();
+        Map<String, Object> data = new HashMap<>();
         data.put("bannerInfo", bannerInfo);
         return ResponseUtil.ok(data);
     }
 
     /**
-     * 大家都在看的商品
+     * 商品页面推荐商品
+     *
+     * @return 商品页面推荐商品
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              goodsList: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("related")
+    @GetMapping("related")
     public Object related(Integer id) {
         if(id == null){
-            return ResponseUtil.fail402();
+            return ResponseUtil.badArgument();
         }
 
         LitemallGoods goods = goodsService.findById(id);
+        if(goods == null){
+            return ResponseUtil.badArgumentValue();
+        }
+
+        // 目前的商品推荐算法仅仅是推荐同类目的其他商品
         int cid = goods.getCategoryId();
 
         // 查找六个相关商品
         int related = 6;
         List<LitemallGoods> goodsList = goodsService.queryByCategory(cid, 0, related);
-        Map<String, Object> data = new HashMap();
+        Map<String, Object> data = new HashMap<>();
         data.put("goodsList", goodsList);
         return ResponseUtil.ok(data);
     }
 
     /**
-     * 　　在售的商品总数
+     * 在售的商品总数
+     *
+     * @return 在售的商品总数
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              goodsCount: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("count")
+    @GetMapping("count")
     public Object count() {
         Integer goodsCount = goodsService.queryOnSale();
-        Map<String, Object> data = new HashMap();
+        Map<String, Object> data = new HashMap<>();
         data.put("goodsCount", goodsCount);
         return ResponseUtil.ok(data);
     }

litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxHomeController.java

@@ -6,6 +6,7 @@ import org.linlinjava.litemall.db.domain.*;
 import org.linlinjava.litemall.db.service.*;
 import org.linlinjava.litemall.db.util.ResponseUtil;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
@@ -34,8 +35,25 @@ public class WxHomeController {
 
     /**
      * app首页
+     *
+     * @return app首页相关信息
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              banner: xxx,
+     *              channel: xxx,
+     *              newGoodsList: xxx,
+     *              hotGoodsList: xxx,
+     *              topicList: xxx,
+     *              floorGoodsList: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("/index")
+    @GetMapping("/index")
     public Object index() {
         Map<String, Object> data = new HashMap<>();
 

litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxRegionController.java

@@ -6,6 +6,7 @@ import org.linlinjava.litemall.db.domain.LitemallRegion;
 import org.linlinjava.litemall.db.service.LitemallRegionService;
 import org.linlinjava.litemall.db.util.ResponseUtil;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
@@ -19,10 +20,26 @@ public class WxRegionController {
     @Autowired
     private LitemallRegionService regionService;
 
-    @RequestMapping("list")
+    /**
+     * 区域数据
+     *
+     * 根据父区域ID，返回子区域数据。
+     * 如果父区域ID是0，则返回省级区域数据；
+     *
+     * @param pid 父区域ID
+     * @return 区域数据
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data: xxx
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
+     */
+    @GetMapping("list")
     public Object list(Integer pid) {
         if(pid == null){
-            return ResponseUtil.fail402();
+            return ResponseUtil.badArgument();
         }
 
         List<LitemallRegion> regionList = regionService.queryByPid(pid);

litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxSearchController.java

@@ -7,6 +7,8 @@ import org.linlinjava.litemall.db.service.LitemallSearchHistoryService;
 import org.linlinjava.litemall.db.util.ResponseUtil;
 import org.linlinjava.litemall.wx.annotation.LoginUser;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
@@ -23,10 +25,26 @@ public class WxSearchController {
     private LitemallSearchHistoryService searchHistoryService;
 
     /**
-     * 　　index
-     * 用户登录是可选的，如果用户登录，则记录用户的搜索数据
+     * 搜索页面信息
+     *
+     * 如果用户已登录，则给出用户历史搜索记录。
+     *
+     * @param userId 用户ID
+     * @return 搜索页面信息
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *      {
+     *          defaultKeyword: xxx,
+     *          historyKeywordList: xxx,
+     *          hotKeywordList: xxx
+     *      }
+     *  }
+     *  失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("index")
+    @GetMapping("index")
     public Object index(@LoginUser Integer userId) {
         //取出输入框默认的关键词
         LitemallKeyword defaultKeyword = keywordsService.queryDefault();
@@ -47,12 +65,24 @@ public class WxSearchController {
     }
 
     /**
-     * 　　helper
+     * 关键字提醒
+     *
+     * 当用户输入关键字一部分时，可以推荐系统中合适的关键字。
+     *
+     * @param keyword 关键字
+     * @return 合适的关键字
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data: xxx
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("helper")
+    @GetMapping("helper")
     public Object helper(String keyword) {
         if(keyword == null){
-            return ResponseUtil.fail402();
+            return ResponseUtil.badArgument();
         }
 
         Integer page = 1;
@@ -67,12 +97,19 @@ public class WxSearchController {
     }
 
     /**
-     * 　　清楚用户搜索历史
+     * 关键字清理
+     *
+     * 当用户输入关键字一部分时，可以推荐系统中合适的关键字。
+     *
+     * @param userId 用户ID
+     * @return 清理是否成功
+     *   成功则 { errno: 0, errmsg: '成功' }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("clearhistory")
+    @PostMapping("clearhistory")
     public Object clearhistory(@LoginUser Integer userId) {
         if(userId == null){
-            return ResponseUtil.fail401();
+            return ResponseUtil.unlogin();
         }
 
         searchHistoryService.deleteByUid(userId);

litemall-wx-api/src/main/java/org/linlinjava/litemall/wx/web/WxTopicController.java

@@ -4,6 +4,7 @@ import org.linlinjava.litemall.db.domain.LitemallTopic;
 import org.linlinjava.litemall.db.service.LitemallTopicService;
 import org.linlinjava.litemall.db.util.ResponseUtil;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
@@ -20,8 +21,23 @@ public class WxTopicController {
 
     /**
      * 专题列表
+     *
+     * @param page 分页页数
+     * @param size 分页大小
+     * @return 专题列表
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data:
+     *          {
+     *              data: xxx,
+     *              count: xxx
+     *          }
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("list")
+    @GetMapping("list")
     public Object list(@RequestParam(value = "page", defaultValue = "1") Integer page,
                        @RequestParam(value = "size", defaultValue = "10") Integer size) {
         List<LitemallTopic> topicList = topicService.queryList(page, size);
@@ -34,11 +50,21 @@ public class WxTopicController {
 
     /**
      * 专题详情
+     *
+     * @param id 专题ID
+     * @return 专题详情
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data: xxx
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("detail")
+    @GetMapping("detail")
     public Object detail(Integer id) {
         if(id == null){
-            return ResponseUtil.fail402();
+            return ResponseUtil.badArgument();
         }
 
         LitemallTopic topic = topicService.findById(id);
@@ -47,8 +73,18 @@ public class WxTopicController {
 
     /**
      * 相关专题
+     *
+     * @param id 专题ID
+     * @return 相关专题
+     *   成功则
+     *  {
+     *      errno: 0,
+     *      errmsg: '成功',
+     *      data: xxx
+     *  }
+     *   失败则 { errno: XXX, errmsg: XXX }
      */
-    @RequestMapping("related")
+    @GetMapping("related")
     public Object related(Integer id) {
         if(id == null){
             return ResponseUtil.fail402();