从版本2.0.0开始，cpj-swagger更名为swagger4j，顶级包名也更名为com.cpjit.swagger4j，与版本1.x.x 完全不兼容。
swagger4j通过与swagger ui一起快速为您的web项目产生接口文档，并且支持在线测试接口。swagger4j可以很方便的与struts2、spring mvc、servlet集成使用，下面的教程将详细说明如何使用swagger4j。
一. 运行要求
二. 加入依赖JAR文件
三. 配置
四. 标注你的接口
五. 访问接口文档
六. 核心API
七. 示例程序
JDK1.8+
- maven：
<dependency>
<groupId>com.cpjit</groupId>
<artifactId>swagger4j</artifactId>
<version>2.2.0</version>
</dependency>您可以通过三种方式来使用swagger4j。
- 与strut2、SpringMVC、Servlet集成
如果您的web项目是基于strut2或SpringMVC或servlet的，您可以在您的web.xml文件中加入如下代码来快速集成swagger4j：
<filter>
<filter-name>swaggerFilter</filter-name>
<filter-class>com.cpjit.swagger4j.SwaggerFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>swaggerFilter</filter-name>
<url-pattern>/doc/*</url-pattern>
</filter-mapping>- 与spring-boot集成
如果您的项目是基于spring-boot的，您可以创建一个配置类来快速集成swagger4j：
@Configuration
public class SwaggerConfig {
@Bean
public FilterRegistrationBean swaggerFilter() {
FilterRegistrationBean bean = new FilterRegistrationBean();
SwaggerFilter filter = new SwaggerFilter();
bean.setFilter(filter);
bean.setUrlPatterns(Collections.singletonList("/doc/*"));
return bean;
}
}您需要在项目的源文件目录下添加一个swagger.properties文件，并加入以下配置项：
packageToScan=com.cpjit.swagger4j.action
apiDescription=Swagger Demo
apiTitle=Swagger Demo
apiVersion=1.0.0
teamOfService=www.cpj.com
devMode=trueswagger4j的配置信息都必须写在swagger.properties文件里面。具体的配置项及其说明如下：
| 键 | 说明 | 支持版本 |
|---|---|---|
| apiFile | 扫描生成json文件的存放路径 | |
| packageToScan | 扫描的包 | |
| apiDescription | 接口文档描述 | |
| apiTitle | 接口文档标题 | |
| apiVersion | 接口版本 | |
| teamOfService | 服务团队 | |
| apiHost | 接口主机地址 | |
| apiBasePath | 接口基路径 | |
| devMode | 是否启用开发模式，如果开启则每次获取接口文档的时候都会扫描类 | |
| suffix | 接口请求地址后缀，如.action | |
| disabled | 是否关闭swagger4j，一般用于生产环境 | |
| schemes | 支持的请求协议，如http、https | v2.1.4+ |
接下来需要用swagger4j提供的注解来标明你的接口，下面以spring mvc为例来说明如何标注接口，其他方式请参考示例程序。
@Controller
@APIs("/demo")
@RequestMapping("/demo")
public class DemoController {
@API(value="login", summary="示例1", parameters={
@Param(name="username", description="用户名", type="string"),
@Param(name="password", description="密码", type="string", format="password"),
@Param(name="image" , description="图片", type="file", format="binary")
})
@RequestMapping(value="login", method=RequestMethod.POST)
public void login(HttpServletResponse response, String username, String password, MultipartFile image)
throws Exception {
response.setContentType("application/json;charset=utf-8");
JSONWriter writer = new JSONWriter(response.getWriter());
Map<String, String> user = new HashMap<String, String>();
user.put("username", username);
user.put("password", password);
writer.writeObject(user);
writer.flush();
writer.close();
}
}在完成前面的工作之后，您可以部署好您的web项目，然后在浏览器输入以下地址就可以访问接口文档了： https://127.0.0.1:8080/您的项目名/doc/index.html
该注解放在一个类上面，用来表明类中包含作为HTTP接口的方法（被注解@com.cpjit.swagger4j.annotation.API标注了的方法）。
该注解的value用来设置接口的前缀，这和struts2的命名空间很像。使用示例如下：
@APIs("/demo")
public class DemoController {
}该注解放在一个方法上面，用来表明方法是HTTP接口方法，注解的属性说明如下：
与注解@com.cpjit.swagger4j.annotation.APIs的value属性一起来指定接口的地址，例如有如下设置：
@APIs("/demo")
public class DemoController {
@API(value="login"})
public void login()
}
}那么login方法对应的接口地址为： youhost/demo/login
用来指定接口的请求参数，详情参见注解Param的说明。
接口功能简述。
接口功能详细说明。
请求方式，默认是POST。
允许的请求MIME，比如：multipart/form-data、application/xml、application/json默认是application/json; charset=utf-8。
特别说明：
当为 multipart/form-data 时，[Param](#3-注解 @comcpjitswagger4jannotationparam)
的in属性必须为formData，但是in为path、header时Param不用遵循此规则。
1.2.2引入的新属性，表示接口是否已经被废弃，默认是false。
1.2.2引入的新属性，表示是否隐藏接口。
用来说明请求参数，例如：
@API(value="login", summary="示例1", parameters={
@Param(name="username", description="用户名", type="string"),
@Param(name="password", description="密码", type="string", format="password")})
@RequestMapping(value="login", method=RequestMethod.POST)
public void login(HttpServletResponse response, String username, String password) throws Exception {
}这表明该接口需要两个请求参数，及username、password。
注解@com.cpjit.swagger4j.annotation.Param的属性说明如下：
参数名
输入参数类型，可取如下值：
- query - 参数拼接到url中
- body - 参数直接放入请求体中
- operation - restful风格的参数传递
- header - 参数放在请求头中
- formData - 参数通过form表单提交
- 当前请求方式为POST的时候，默认值为formData
- 请求方式为非POST的时候，默认值为query
数据类型, 与format一起指定请求参数的数据类型。
type 和 format 的可选值如下：
| 通用名 | type |
format |
备注 |
|---|---|---|---|
| integer | integer |
int32 |
signed 32 bits |
| long | integer |
int64 |
signed 64 bits |
| float | number |
float |
|
| double | number |
double |
|
| string | string |
||
| byte | string |
byte |
base64 encoded characters |
| binary | string |
binary |
any sequence of octets |
| boolean | boolean |
||
| date | string |
date |
As defined by full-date - RFC3339 |
| dateTime | string |
date-time |
As defined by date-time - RFC3339 |
| password | string |
password |
Used to hint UIs the input needs to be obscured. |
数据格式，type一起指定请求参数的数据类型。
1.2.2引入的新属性，替代type和format来指定数据类型。
参数说明
是否是必须参数， 默认是false
2.1.0引入的新属性，用于指定参数的默认值。
可用的数据类型