背景

在前后端分离开发环境中，后端同事开发好接口后，前端同事需要没有一个浏览所有接口的页面
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","","[email protected]"))
                .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 的位置参数就自动设置到值,然后点试一下将会有返回结果

这里写图片描述

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

【LEAP】整合 Swagger

背景

准备

开始

添加类注解

方法中添加注解

创建Swagger匹配类 RestApiConfig

LEAP.xml配置

Web.xml配置

测试

猜你喜欢