# jfinal-swagger-api

**Repository Path**: jiahaoweiwei/jfinal-swagger-api

## Basic Information

- **Project Name**: jfinal-swagger-api
- **Description**: 基于JFinal的swagger API在线生成，非全包扫描，基于JFinal自身API获取所有Action生成，更安全更高效，借鉴JFinal，追求极简，同时有以下特点：
1.诸多注解属性非必需，包含默认值或自动设定；
2.Controller注解及同一Controller下的Action支持自定义排序；
3.支持自定义全局参数(参考自江南久无雪的https://gitee.com/leeckent/jfinal-swagger)；
4.支持两种主题模式：layui和default，默认layui(使用五只鸭子的https://gitee.com/caspar-chen/Swagger-UI-layer)，default主题为官网默认的(官网提供的js总是有问题，不推荐)。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 10
- **Created**: 2019-11-11
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# jfinal-swagger-api

#### 介绍
基于JFinal的swagger API在线生成，非全包扫描，基于JFinal自身API获取所有Action生成，更安全更高效，借鉴JFinal，追求极简，同时有以下特点：

1. 诸多注解属性非必需，包含默认值或自动设定；
2. Controller注解及同一Controller下的Action支持自定义排序；
3. 支持自定义全局参数(参考自江南久无雪的https://gitee.com/leeckent/jfinal-swagger)；
4. 支持两种主题模式：layui和default，默认layui(使用五只鸭子的https://gitee.com/caspar-chen/Swagger-UI-layer)，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添加注解( **_极少配置即可，多数默认设置或自动设置_** )：

```
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=30)
public class UserController extends Controller {

    @ActionApi(remark="DemoController首页Action（sort非必需）", sort=1)
    public void index() {
        renderJson(Kv.by("user", "Hello JFinal!"));
    }
    
    @ActionApi(remark="输出文本", sort=2)
    @Param(name="text", remark="文本内容")
    public void text() {
        renderText("输出接收文本：<br>" + get("text"));
    }
}
```
4.启动项目，访问http://localhost:8080/swagger.

#### 截图展示
![输入图片说明](https://images.gitee.com/uploads/images/2019/0305/233521_16a3452b_58975.png "screenshot1.png")
![输入图片说明](https://images.gitee.com/uploads/images/2019/0305/233536_a6add956_58975.png "screenshot2.png")
![输入图片说明](https://images.gitee.com/uploads/images/2019/0305/233546_dcad7193_58975.png "screenshot3.png")
![输入图片说明](https://images.gitee.com/uploads/images/2019/0305/233555_7c930dc0_58975.png "screenshot4.png")



 **各注解使用演示** ( **_大部分属性可以使用默认或未指定时会自动设定，这里仅做演示_** ):

```
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));
    }
}
```