【LEAP】整合 Swagger

背景

在前后端分离开发环境中，后端同事开发好接口后，前端同事需要没有一个浏览所有接口的页面
LEAP中是通过 /restservices 访问所有发布的接口，界面不是特别友好

Swagger 是基于REST API测试/文档类插件，由于LEAP中可能存在第三方包不兼容的问题（没有针对原Swagger服务包做兼容测试，本着能少引用包就少引用的想法），我将自己开发一个Swagger服务类整理在WebUtil.BLL.jar中，具体实现之后再说，先将如何使用。

准备

• 下载最新WebUtil.BLL.jar

开始

添加类注解

• @RestController此注释相当于告诉程序这个类需要被解析成Swagger ui
• @Api(name = "WeChat", description = "微信") name 分类名称 description 本类的描述信息.

以上两个注释缺一不可!

方法中添加注解

• @ApiOperation(value="方法名", notes="notes") - 方法名称和说明.

@RestController@Api(name = "WeChat", description = "微信")public class WeChatService extends LEAPContextService{}

• @ApiImplicitParams({@ApiImplicitParam ,... ,@ApiImplicitParam}) 参数描写,目前LEAPWeb中所有曝光的参数都要求只传EntityBean.比如,方法要接收两个参数name 和 age ,那就请将这两个放到EntityBean中 , 然后将EntityBean传给方法,特殊例外,这样写的好处是方便之后扩展.我们还要将方法中必须用到的参数写到注解中,这样方便前端调试.
  
  • name参数名称.
  • value 参数中文名称.
  • example 测试数据.
  • 其他带完善,目前只用这三个,但是其他的还是要填上.

package com.longrise.LPOM;import com.longrise.LEAP.Base.Logic.LogicManager;import com.longrise.LEAP.Base.Objects.EntityBean;import com.longrise.LEAP.Base.Session.LEAPContextService;import com.longrise.LPOM.BLL.Logic.WeChatLogic;import com.longrise.bind.Result.JsonResult;import com.longrise.bind.annotation.Api;import com.longrise.bind.annotation.ApiImplicitParam;import com.longrise.bind.annotation.ApiImplicitParams;import com.longrise.bind.annotation.ApiOperation;import com.longrise.bind.annotation.RequestMapping;import com.longrise.bind.annotation.RequestMethod;import com.longrise.bind.annotation.RestController;@RestController@Api(name = "WeChat", description = "微信")public class WeChatService extends LEAPContextService{    /**     * <p>Title: 发送模板消息</p>     * <p>Description:发送模板消息</p>     * @author Lix     * @date 2017年2月27日19:38:30     * @tags @return JsonResult     */    @ApiOperation(value="发送模板消息", notes="")//针对api的描述  value 简单描述  notes 详细描述    @ApiImplicitParams({        @ApiImplicitParam(name = "method",    value = "方法名称",   example="sendTemplate", required = true, dataType = "String"),        @ApiImplicitParam(name = "touser",    value = "用户",         example="oxt3ew0idjb3hj195K1JoPo2sEy8", required = true, dataType = "String"),        @ApiImplicitParam(name = "template_id",       value = "模板id",   example="cGcgQq9CY_UFXoryp0OymytNrNyHfeCSE84mZRShG-0", required = true, dataType = "String"),        @ApiImplicitParam(name = "title",     value = "模板数据",   example="您好,您有一条待办件", required = true, dataType = "String"),        @ApiImplicitParam(name = "businame",      value = "模板数据",   example="事项名称", required = true, dataType = "String"),        @ApiImplicitParam(name = "busiinfo",      value = "模板数据",   example="事项摘要", required = true, dataType = "String"),    })    @RequestMapping(value="#sendTemplate", method = RequestMethod.POST, L=true , consumes = "application/json" )    public JsonResult sendTemplate(EntityBean bean){        WeChatLogic weChatLogic = new WeChatLogic();        LogicManager.getInstance().setLogic(this , weChatLogic);        return weChatLogic.sendTemplate(bean);    }}

创建Swagger匹配类 RestApiConfig

• basePackage添加service 类
• description 描述信息
• title 标题
• termsOfServiceUrl 服务反馈地址或者官网
• contact 开发者
• version 版本号
  目前一个包一个类就够了.

package com.longrise.LPOM.BLL.Util;import com.longrise.LEAP.Base.Objects.EntityBean;import com.longrise.bind.documentation.builders.ApiInfoBuilder;import com.longrise.bind.documentation.service.ApiInfo;import com.longrise.bind.documentation.service.Contact;import com.longrise.bind.documentation.service.DocInit;/** * 一个项目一个就ok -By Lix. * <p>Title: </p> * <p>Description: </p> * @author Administrator * @date Nov 22, 2016 9:59:42 AM */public class RestApiConfig {    public DocInit createRestApi(EntityBean bean) {        return new DocInit(bean)                .apiInfo(apiInfo())                .basePackage(new String[]{"com.longrise.LPOM.WeChatService"})                .build();    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .description("微信接口")                .title("ASCT RESTful API")                .termsOfServiceUrl("http://www.longrise.com.cn")                .contact(new Contact ("lix","","[e-mail]"))                .version("1.0")                .build();    }}

LEAP.xml配置

• 添加要发布的classes service.
• publishRestService 中WebUnifyPort 为统一请求方法.
• ApiDoc是 Swagger匹配类.

<RPCService name="web" websites="*">            <classes>                <class>com.longrise.LPOM.LPOMWebService</class>                <class>com.longrise.bind.Service.WebUnifyPortService</class><!-- 前端统一请求接口 -->                <class>com.longrise.LPOM.WeChatService</class>            </classes>            <!--定义发布的服务-->            <publish>                <service>*</service>            </publish>            <publishRestService>                <service>WebUnifyPort</service>            </publishRestService>            <!--ApiDoc-->            <ApiDoc>                <class>com.longrise.bind.common.RestApiConfig</class>                <class>com.longrise.LPOM.BLL.Util.RestApiConfig</class>            </ApiDoc>        </RPCService>

Web.xml配置

<servlet>        <servlet-name>SwaggerJSON</servlet-name>        <servlet-class>            com.longrise.bind.Swagger.SwaggerJSON        </servlet-class>    </servlet>    <servlet-mapping>        <servlet-name>SwaggerJSON</servlet-name>        <url-pattern>/Swagger.do</url-pattern>    </servlet-mapping>

测试

• 打开 http://192.168.5.200:9201/LPOM/LEAP/swagger/index.html?type=LPOM,type为你要访问的包名称,因为可以很多包都放在一个项目中,所以根据包名来区分.
  

• 如果你上面配置的都没有问题那么直接点 1 的位置 参数就自动设置到值,然后点试一下将会有返回结果

(以后会慢慢完善,现在还处于测试期,如果你有更好的想法,可以和我联系!)