easyopen提供一个简单的api文档查看页面,类似于swagger,基于注解功能来生成文档页面。生成的文档页面可以查看参数、结果说明,也可以进行模拟请求。对于前后端分离的项目来说会很有帮助。文档界面如下图所示:
左边的树形菜单对应文档名称,点击树可前往查看对应的接口说明。点击请求按钮可以发起请求进行测试。可修改业务参数中的值进行测试。
下面来讲解文档注解的使用方法。
文档页面默认是关闭的,需要在ApiConfig中设置
apiConfig.setShowDoc(true);// 为true开启文档页面。
接下来对获取商品接口设置文档信息:
@Api(name = "goods.get") public Goods getGoods(GoodsParam param) { ... return goods; }
在接口方法上添加一个@ApiDocMethod注解。
@Api(name = "goods.get") @ApiDocMethod(description="获取商品") // 文档注解,description为接口描述 public Goods getGoods(GoodsParam param) { ... return goods; }
进入GoodsParam类,使用@ApiDocField注解
public class GoodsParam { @ApiDocField(description = "商品名称", required = true, example = "iphoneX") private String goods_name; // 省略 get set }
@ApiDocField注解用来定义字段信息,@ApiDocField注解定义如下
/** * 字段描述 */ String description() default ""; /** * 字段名 */ String name() default ""; /** * 数据类型,int string float * @return */ DataType dataType() default DataType.STRING; /** * 是否必填 */ boolean required() default false;
同样,在Goods类中设置@ApiDocField
public class Goods { @ApiDocField(description = "id") private Long id; @ApiDocField(description = "商品名称") private String goods_name; @ApiDocField(description = "价格", dataType = DataType.FLOAT) private BigDecimal price; // 省略 get set }
到此已经设置完毕了,可以访问url进行预览
文档页面的url格式为:apiUrl + “/doc”。如:apiUrl为 http://localhost:8080/api/v1 ,那么文档页面就是: http://localhost:8080/api/v1/doc
如果接口方法返回一个List,设置方式如下
@Api(name = "goods.list", version = "2.0") @ApiDocMethod(description="获取商品列表" ,results={@ApiDocField(description="商品列表",name="list", elementClass=Goods.class)} ) public List<Goods> listGoods(GoodsParam param) { }
elementClass对应List中的元素类型
如果有个一个PageInfo类,是第三方jar中的,没办法对其修改,那要如何对它里面的属性编写对应文档呢。
PageInfo类内容如下:
// 假设这是jar中的类,没法修改。但是要对其进行文档生成 public class PageInfo<T> { private int pageIndex; private int pageSize; private long total; // 省略 get set }
我们可以显式的声明字段信息:
@Api(name = "goods.pageinfo", version = "1.0") @ApiDocMethod(description="获取商品列表" ,results={@ApiDocField(name="pageIndex",description="第几页",dataType=DataType.INT,example="1"), @ApiDocField(name="pageSize",description="每页几条数据",dataType=DataType.INT,example="10"), @ApiDocField(name="total",description="每页几条数据",dataType=DataType.LONG,example="100"), @ApiDocField(name="rows",description="数据",dataType=DataType.ARRAY,elementClass=Goods.class),} ) public PageInfo<Goods> pageinfo(GoodsParam param) { }
如果多个接口都返回PageInfo,需要复制黏贴大量的注解,改一个地方需要改多个接口,无法达到复用效果。我们可以新建一个GoodsPageVo继承PageInfo,然后把文档注解写在类的头部,这样可以达到复用效果。
@ApiDocBean(fields = { @ApiDocField(name="pageIndex",description="第几页",dataType=DataType.INT,example="1"), @ApiDocField(name="pageSize",description="每页几条数据",dataType=DataType.INT,example="10"), @ApiDocField(name="total",description="每页几条数据",dataType=DataType.LONG,example="100"), @ApiDocField(name="rows",description="商品列表",dataType=DataType.ARRAY,elementClass=Goods.class), }) public class GoodsPageVo extends PageInfo<Goods> { }
@Api(name = "goods.pageinfo", version = "2.0") @ApiDocMethod(description="获取商品列表",resultClass=GoodsPageVo.class) public PageInfo<Goods> pageinfo2(GoodsParam param) { }
使用resultClass=GoodsPageVo.class指定返回结果类型即可。