swagger4j

从版本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+

二. 加入依赖JAR文件

• maven：

<dependency>
	<groupId>com.cpjit</groupId>
	<artifactId>swagger4j</artifactId>
	<version>2.2.0</version>
</dependency>

三. 配置

1. 选择使用方式

您可以通过三种方式来使用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;
    }
}

2. 修改配置项

您需要在项目的源文件目录下添加一个swagger.properties文件，并加入以下配置项：

packageToScan=com.cpjit.swagger4j.action
apiDescription=Swagger Demo
apiTitle=Swagger Demo
apiVersion=1.0.0
teamOfService=www.cpj.com
devMode=true

swagger4j的配置信息都必须写在swagger.properties文件里面。具体的配置项及其说明如下：

四. 标注你的接口

接下来需要用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项目，然后在浏览器输入以下地址就可以访问接口文档了： http://127.0.0.1:8080/您的项目名/doc/index.html

六. 核心API

1. 注解 @com.cpjit.swagger4j.annotation.APIs

该注解放在一个类上面，用来表明类中包含作为HTTP接口的方法（被注解@com.cpjit.swagger4j.annotation.API标注了的方法）。 该注解的value用来设置接口的前缀，这和struts2的命名空间很像。使用示例如下：

@APIs("/demo")
public class DemoController {
  
}

2. 注解 @com.cpjit.swagger4j.annotation.API

该注解放在一个方法上面，用来表明方法是HTTP接口方法，注解的属性说明如下：

value

与注解@com.cpjit.swagger4j.annotation.APIs的value属性一起来指定接口的地址，例如有如下设置：

@APIs("/demo")
public class DemoController {
  	@API(value="login"})
	public void login()
	}
}

那么login方法对应的接口地址为： youhost/demo/login

parameters

用来指定接口的请求参数，详情参见注解Param的说明。

summary

接口功能简述。

description

接口功能详细说明。

method

请求方式，默认是POST。

consumes

允许的请求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不用遵循此规则。

deprecated

1.2.2引入的新属性，表示接口是否已经被废弃，默认是false。

hide

1.2.2引入的新属性，表示是否隐藏接口。

3. 注解 @com.cpjit.swagger4j.annotation.Param

用来说明请求参数，例如：

@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的属性说明如下：

name

参数名

in

输入参数类型，可取如下值：

• query - 参数拼接到url中
• body - 参数直接放入请求体中
• operation - restful风格的参数传递
• header - 参数放在请求头中
• formData - 参数通过form表单提交

• 当前请求方式为POST的时候，默认值为formData
• 请求方式为非POST的时候，默认值为query

~~type~~

数据类型, 与format一起指定请求参数的数据类型。 type 和 format 的可选值如下：

~~format~~

数据格式，type一起指定请求参数的数据类型。

dataType

1.2.2引入的新属性，替代type和format来指定数据类型。

description

参数说明

required

是否是必须参数， 默认是false

defaultValue

2.1.0引入的新属性，用于指定参数的默认值。

4.枚举 com.cpjit.swagger4j.annotation.DataType

可用的数据类型

七. 示例程序

• Spring MVC