（九）生成文档页面

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

文档页面的url格式为：apiUrl + “/doc”。如：apiUrl为http://localhost:8080/api/v1，那么文档页面就是：http://localhost:8080/api/v1/doc

List返回

如果接口方法返回一个List，设置方式如下

    @Api(name = "goods.list", version = "2.0")
    @ApiDocMethod(description="获取商品列表"
        ,results={@ApiDocField(description="商品列表",name="list", elementClass=Goods.class)}
    )
    public List listGoods(GoodsParam param) {

    }

elementClass对应List中的元素类型

第三方类返回

如果有个一个PageInfo类，是第三方jar中的，没办法对其修改，那要如何对它里面的属性编写对应文档呢。

PageInfo类内容如下：

// 假设这是jar中的类，没法修改。但是要对其进行文档生成
public class PageInfo {
    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 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 pageinfo2(GoodsParam param) {

    }

使用resultClass=GoodsPageVo.class指定返回结果类型即可。