(九)生成文档页面

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<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指定返回结果类型即可。

原文 

https://blog.csdn.net/thc1987/article/details/80090913

本站部分文章源于互联网,本着传播知识、有益学习和研究的目的进行的转载,为网友免费提供。如有著作权人或出版方提出异议,本站将立即删除。如果您对文章转载有任何疑问请告之我们,以便我们及时纠正。

PS:推荐一个微信公众号: askHarries 或者qq群:474807195,里面会分享一些资深架构师录制的视频录像:有Spring,MyBatis,Netty源码分析,高并发、高性能、分布式、微服务架构的原理,JVM性能优化这些成为架构师必备的知识体系。还能领取免费的学习资源,目前受益良多

转载请注明原文出处:Harries Blog™ » (九)生成文档页面

赞 (0)
分享到:更多 ()

评论 0

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址