【JFINAL】——JFinal 整合 Swagger 详细流程

如有侵权，请告知删除。综合前边的答案整理而成。

 

 

参考网址：

http://blog.youkuaiyun.com/time_travel/article/details/78412321

Swagger API 网址：

http://blog.youkuaiyun.com/jun55xiu/article/details/70316851

注解解释：

http://docs.swagger.io/swagger-core/v1.3.12/apidocs/index.html?com/wordnik/swagger/annotations/ApiResponse.html

 

 

一、到码云上获取jfinal-swagger源码并打包成jar

git下载地址： git@gitee.com:leeckent/jfinal-swagger.git

打包方式：

①： 下载好进行编译以后，执行jar命令打包：jar cvf jfinal-swagger.jar -C classes/ （classes目录为编译后的文件跟目录）

②： Eclipse / MyEclipse : 右键选中项目 -- Export -- JAR.file 导出生产jar包选择存储地址。

③： - mvn clean

- mvn install

二、到github上获取swaggerui

https://github.com/swagger-api/swagger-ui.git

 

三、相关配置，引入swagger到项目中

 

#### JFinal-Swagger 使用说明

 

**1. 添加依赖**

```

<dependency>

<groupId>com.feizhou</groupId>

<artifactId>jfinal-swagger</artifactId>

<version>1.0-SNAPSHOT</version>

</dependency>

```

 

**2. 下载 swagger-ui-master 将 dist 中文件加入到项目中**

 

```

可配置成类似如下路径：

webapp

static

swagger

favicon-16x16.png

...

swagger-ui.js.map

WEB-INF

views

swagger

index.html

```

 

**3. 增加Swagger路由控制**

 

```

/**

* 配置路由

*/

public void configRoute(Routes me) {

me.add("/",LoginController.class);

me.add("/swagger", SwaggerController.class);

}

```

 

 

**4. 添加注解**

 

```

提供四种注解：

@Api(tag = "index", description = "测试输出")

@ApiOperation(url = "/test", tag = "index", httpMethod = "get", description = "测试json")

@Param(name = "id", description = "编号", required = true, dataType = "Long")

@Params

```

 

**5. config.properties

#配置扫描包信息

swagger.base_package=ibasic.web.com.controller

#增加文件参数支持

consumes = "multipart/form-data"

#配置扫描包信息

dataType ="file"

 

**6.index.html 中修改url

***js

<script>

window.onload = function() {

// Build a system

const ui = SwaggerUIBundle({

// url: "http://petstore.swagger.io/v2/swagger.json",

url: "/swagger/api", //修改url

dom_id: '#swagger-ui',

validatorUrl: false,

deepLinking: true,

presets: [

SwaggerUIBundle.presets.apis,

SwaggerUIStandalonePreset

],

plugins: [

SwaggerUIBundle.plugins.DownloadUrl

],

layout: "StandaloneLayout"

})

window.ui = ui

}

</script>

***

 

注解使用示例：

 

```java

@Api(tag = "index", description = "测试输出")

public class LoginController extends Controller {

 

 

@ApiOperation(url = "/add", tag = "登录", httpMethod = "post", description = "用户增加")

@Params({@Param(name = "id", required = true, dataType="integer",description = "用户ID",defaultValue="1111"),

@Param(name = "name", required = true, dataType="string",description = "用户姓名")

})

public void add() {

JSONObject jo = new JSONObject();

jo.put("name", "想对对对");

jo.put("age", "想对对对");

jo.put("ddd", "想对对对");

jo.put("aaaa", "想对对对");

renderJson(jo);

}

}

```

 

四、如果增加注解，可查看 swagger API 中说明。其次修改SwaggerController中代码。

 

SwaggerController 代码示例如下：

 

} else if (Param.class == annotationType) {

Param apiParam = (Param) annotation;

apiMethod.addParameter(new SwaggerPath.Parameter(apiParam.name(), apiParam.description(),

apiParam.required(), apiParam.dataType(), apiParam.format(), apiParam.defaultValue()));

} else if (ApiResponse.class == annotationType) {

ApiResponse response = (ApiResponse) annotation;

apiMethod.addResponse("", new SwaggerResponse(response.message()));

}

 

五、报错解决方法

 

1.正产页面出现生成文档后有边角有 {error} 标志。点开后报错信息为：Can`t read from file /swagger/api

解决方法为：index.html 中增加

 

window.onload = function() {

// Build a system

const ui = SwaggerUIBundle({

// url: "http://petstore.swagger.io/v2/swagger.json",

url: "/swagger/api",

dom_id: '#swagger-ui',

validatorUrl: false,// 添加此属性即可解决。

deepLinking: true,

presets: [

SwaggerUIBundle.presets.apis,

SwaggerUIStandalonePreset

],

plugins: [

SwaggerUIBundle.plugins.DownloadUrl

],

layout: "StandaloneLayout"

})

 

window.ui = ui

}

 

效果图：