根据Swagger2可以快速帮助我们编写最新的API接口文档，再也不用担心开会前仍忙于整理各种资料了，间接提升了团队开发的沟通效率。

1. 引入依赖

    <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>

2. 添加配置

@Configuration //标记配置类 @EnableSwagger2 //开启在线接口文档

/** * Swagger配置类 * @author bfy--lujian * @version 1.0.0 * 创建时间：2018/8/1 * @email bfyjian@gmail.com */ @Configuration //标记配置类 @EnableSwagger2 //开启在线接口文档 public class SwaggerConfig {

    /\*\*
     \* 添加摘要信息(Docket)
     \*/
    @Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER\_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("大江区块链技术有限公司\_商城系统\_接口文档")
                        .description("描述：用于线上用户购买商品,具体包括XXX,XXX模块...")
                        .contact(new Contact("lujian", "hppt://www.bfylu.top", "bfyjian@gmail.com"))
                        .version("版本号:1.0")
                        .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.platform.api"))
                .paths(PathSelectors.any())
                .build();
    }

}

3. 编写接口文档

Swagger2 基本使用：

@Api 描述类/接口的主要用途
@ApiOperation 描述方法用途
@ApiImplicitParam 描述方法的参数
@ApiImplicitParams 描述方法的参数(Multi-Params)
@ApiIgnore 忽略某类/方法/参数的文档

Swagger2 使用注解来编写文档：

Swagger2编写接口文档相当简单，只需要在控制层（Controller）添加注解来描述接口信息即可。例如：

@Api(tags = "关注商家") @RestController @RequestMapping(value = "userCollection") public class UserCollectionController extends BaseController {

@Autowired
private UserCollectionService userCollectionService;

@Autowired
private GoodsService goodsService;

@Autowired
private ShopService shopService;


@PostMapping("/add")
@ApiOperation("收藏店铺接口 -> 卢健")
//@HystrixCommand(fallbackMethod = "addUserError")
public BaseResp addUserCollection(UserCollectionDto userCollectionDto) {
    UserCollection userCollection = JsonUtil.convert(userCollectionDto, UserCollection.class);
    boolean ok = userCollectionService.insertSelective(userCollection);
    if (!ok) {
        return BaseResp.fail("收藏店铺失败");
    }
    return BaseResp.success("收藏店铺成功");
}

@GetMapping("/findByCondition")
@ApiOperation("查询用户收藏的店铺信息 -> 卢健")
public BaseResp<PageInfo<UserCollectionVo>> getUserCollectionByPage(
        @ApiParam(name = "userId", value = "用户Id") @RequestParam(name = "userId", required = true) String userId,
        @ApiParam(name = "pageNum", value = "当前页") @RequestParam(name = "pageNum", required = false, defaultValue = "1") int pageNum,
        @ApiParam(name = "pageSize", value = "每页条数") @RequestParam(name = "pageSize", required = false, defaultValue = "10") int pageSize
) {
    List<UserCollection> userCollectionLists = userCollectionService.findByUserId(userId);

    //List去重
    List<UserCollection> setList= new ArrayList<>();
    Set<String> set= new HashSet<>();
    for (UserCollection userCollection : userCollectionLists) {
        if (userCollection == null) {
            continue;
        }
        String  merCode = userCollection.getMerCode();
        if (merCode != null) {
            if (!set.contains(merCode)) { //set中不包含重复的
                set.add(merCode);
                setList.add(userCollection);
            } else {
                continue;
            }
        }
    }
    set.clear();
    
    PageHelper.startPage(pageNum, pageSize);
    PageInfo<UserCollection> pageInfoUserCollection = new PageInfo<>(setList);

    List<Map<String, String>> goodsList = new ArrayList<>();
    Map<String, String> goodsMap = new HashMap<>();
    //取出需要转换的页内容
    List<UserCollection> userCollectionList = pageInfoUserCollection.getList();//屏蔽一些字段，只显示TuserVo中的字段
    //屏蔽一些字段，只显示TuserVo中的字段
    List<UserCollectionVo> listUserCollectionVo = JsonUtil.convertList(userCollectionList, UserCollectionVo.class);
    for (UserCollectionVo userCollectionVo : listUserCollectionVo) {
        for (UserCollection s : userCollectionLists) {
           if (userCollectionVo.getMerCode().equals(s.getMerCode())){
               JSONObject goodsInfo = JSONObject.parseObject(s.getGoodsInfo());
               String refNo = goodsInfo.getString("refNo");
               String primary = goodsInfo.getString("primary");
               String goodsPrice = goodsInfo.getString("goodsPrice");
               goodsMap.put("refNo", refNo);
               goodsMap.put("primary", primary);
               goodsMap.put("goodsPrice", goodsPrice);
               goodsList.add(goodsMap);
           }
            }
        String shopGoodsInfo = "";
        ObjectMapper objectMapper = new ObjectMapper();
        try {
            shopGoodsInfo =  objectMapper.writeValueAsString(goodsList);
        } catch (JsonProcessingException e) {
            e.printStackTrace();
        }
        log.info(shopGoodsInfo);
        userCollectionVo.setShopHotGoodsList(shopGoodsInfo);
        Shop shop = shopService.queryFroMerCode(userCollectionVo.getMerCode());
        userCollectionVo.setShopLogo(shop.getShopLogo());
        userCollectionVo.setShopName(shop.getShopName());
        userCollectionVo.setShopNo(shop.getShopNo());
        userCollectionVo.setShopTotalSale(goodsService.countGoodsSale(userCollectionVo.getMerCode()));
    }
    //把原来的分页数据拷贝过来，如：当前页,每页的数量,总记录数,总页数,是否为第一页,是否为最后一页
    PageInfo<UserCollectionVo> pageInfoVo = JsonUtil.convert(pageInfoUserCollection, UserCollectionVo.class);
    //放入转换后的内容
    pageInfoVo.setList(listUserCollectionVo);
    return BaseResp.success("收藏店铺信息显示成功",pageInfoVo);
}

}

dto【对应于除二者(do,vo)之外需要进行传递的数据】添加注解来描述接口信息

@Setter @Getter @NoArgsConstructor public class GoodsDto extends Goods {

@ApiParam("商品销量")
private Integer goodsSales;

@ApiParam("排序规则")
private boolean sortRule;

}

vo【对应于页面上需要显示的数据（表单）】添加注解来描述接口信息

/** *

商户推荐信息

* @author bfy--lujian * @version 1.0.0 * 创建时间：2018/7/17 16:12 * @email bfyjian@gmail.com */

@Setter @Getter @NoArgsConstructor @ApiModel(description= "返回响应数据") public class ShopRecommend {

@ApiModelProperty("商户编号")
private String merCode;
@ApiModelProperty("商户名称")
private String username;
@ApiModelProperty("店铺名称")
private String shopName;
@ApiModelProperty("商品数量")
private Long countGoods;
@ApiModelProperty("当前销量")
private Long countGoodsSale;
@ApiModelProperty("countGoodsSale")
private Date openTime;

}