基于JFinal集成swagger,力求极简

自己的一个JFinal小项目,想加入swagger API,于是寻找已有的集成方案,集成过程中也是折腾了一番,中间感觉还是不够简化,于是动手重新整合写了一个,还不完善,后续会继续完善。实现过程中使用和参考借鉴了江南久无雪的https://gitee.com/leeckent/jfinal-swagger 以及五只鸭子的前端样式https://gitee.com/caspar-chen/Swagger-UI-layer,感谢两位的分享。

源码下载地址:https://gitee.com/luketech/jfinal-swagger-api

目前特点:

1.诸多注解属性非必需,包含默认值或自动设定;
2.Controller注解及同一Controller下的Action支持自定义排序;
3.支持自定义全局参数;
4.支持两种主题模式:layui和default,默认layui,default主题为官网默认的(官网提供的js总是有问题,不推荐)。

使用介绍:

1.将本项目源码加入到实际项目中(如需修改包名,请自行修改)
2.JFinalConfig类中配置如下内容:

public class AppConfig extends JFinalConfig {
    /**
     * 配置访问路由
     * @param me
     */
    @Override
    public void configRoute(Routes me) {
        // 配置Swagger UI访问路由
        me.add(new SwaggerRoute());
    }
    /**
     * JFinal启动完成后的操作
     */
    @Override
    public void onStart() {
    // 添加全局参数(如token,非必需)
        SwaggerConfig.addGlobalParam("x-access-token", "token令牌", "string", "jfinal-awesome-token", true, "", InType.HEADER);
    }
}

3.Controller添加注解: 常用极少配置的Demo:

import com.jfinal.core.Controller;
import com.jfinal.kit.Kv;
import com.jfinal.swagger.annotation.ActionApi;
import com.jfinal.swagger.annotation.Api;
import com.jfinal.swagger.annotation.Param;

@Api(remark="UserController,排序到末尾", sort=2)
public class UserController extends Controller {

    @ActionApi(remark="DemoController首页Action")
    public void index() {
        renderJson(Kv.by("user", "Hello JFinal!"));
    }
    
    @ActionApi(remark="输出文本")
    @Param(name="text", remark="文本内容")
    public void text() {
        renderText("输出接收文本:<br>" + get("text"));
    }
}

所有支持的配置Demo演示(大部分属性可以使用默认或未指定时会自动设定,这里仅做演示):

import java.util.Arrays;

import com.jfinal.core.Controller;
import com.jfinal.kit.Kv;
import com.jfinal.swagger.annotation.ActionApi;
import com.jfinal.swagger.annotation.Api;
import com.jfinal.swagger.annotation.Param;
import com.jfinal.swagger.annotation.Params;
import com.jfinal.swagger.enums.InType;

@Api(tag="/", remark="首页Controller", sort=10, outerRemark="查看更多关于首页", outerUrl="https://www.baidu.com/s?wd=JFinal")
public class IndexController extends Controller {

    @ActionApi(tag="/", remark="IndexController首页Action", summary="首页", sort=2)
    public void index() {
        renderJson(Kv.by("index", "Hello JFinal!"));
    }
    
    @ActionApi(tag="/", remark="欢迎加入JFinal俱乐部", httpMethod="post", sort=1, consumes="application/json", url="/club")
    @Params({
        @Param(name="memberName", remark="会员", dataType="string", defaultValue="James", required=true, in=InType.QUERY, format="", schema="http"),
        @Param(name="memberId", remark="会员ID", dataType="integer", defaultValue="88888", required=true, minimum="1", maximum="999999"),
        @Param(name="level", remark="会员等级", dataType="integer", defaultValue="8")
    })
    public void club() {
        String memberName = get("memberName");
        int memberId = getInt("memberId");
        int level = getInt("level");
        Kv cnKv = Kv.by("welcome", memberName + ":欢迎加入JFinal俱乐部!").set("memberId", memberId).set("level", level);
        Kv enKv = Kv.by("welcome", memberName + ":Welcome to JFinal club!").set("memberId", memberId).set("level", level);
        renderJson(Arrays.asList(cnKv, enKv));
    }
}

4.启动项目,访问http://localhost:8080/swagger.
效果图如下:

screenshot1.png

screenshot2.png

screenshot3.png



评论区

nicolasOne

2019-03-06 10:45

可以,这个注解挺多的

JFinal

2019-03-06 10:51

越做越好,收藏加点赞

冰雨

2019-03-06 16:22

@nicolasOne 大部分注解可以默认,不用设置

maxwade

2019-03-07 09:06

开源中国上面有个smart-doc,因为swagger使用注解过多时,导致代码太难看了

zzhkiller

2019-03-07 09:45

可以把注解和参数 写在json 中

冰雨

2019-03-07 10:54

@zzhkiller 写在json是什么意思?没太明白

冰雨

2019-03-07 10:56

@maxwade 注解多可以满足更多多样性需求,但是常规需求如果还要写太多注解就不方便了

yyyyangzi

2019-03-07 17:18

生产环境中,怎么禁用swagger?

冰雨

2019-03-07 22:04

@yyyyangzi config添加swagger路由的地方加个判断,生产环境不添加路由即可

flash866

2019-03-12 08:47

为啥不用APIZZA?

王IT

2019-03-12 16:50

我不喜欢swagger对代码的植入....

l745230

2019-04-19 11:13

集成了下,发现一个问题,两个controller有个方法名相同,如果只对controller配置了tag,没对方法配置tag,则只会有一个controller生成api

冰雨

2019-04-23 09:40

@l745230 最近几天忙,没及时回复,刚在本机试了下,是可以的,没发现你说的问题,现在问题解决了吗?

l745230

2019-04-23 17:39

@冰雨 之前swagger注解用的配置太全了,最后全删了,只留下remark等几个必须的. 然后就没问题了. 简单点好,看上去也舒服点..

cs3230524

2019-09-29 22:07

你们都不用解释返回的字段吗,response 都不要?