cpj-swagger
原文地址：/3cpj/swagger
1. Swagger是什么？
官方说法：Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
个人觉得，swagger的一个最大的优点是能实时同步api与文档。在项目开发过程中，发生过多次：修改代码但是没有更新文档，前端还是按照老旧的文档进行开发，在联调过程中才发现问题的情况（当然依据开闭原则，对接口的修改是不允许的，但是在项目不稳定阶段，这种情况很难避免）。
cpj-swagger通过与swagger ui一起快速为您的web项目产生接口文档，并且支持在线测试接口。cpj-swagger可以很方便的与struts2、spring mvc、servlet集成使用，下面的教程将详细说明如何使用cpj-swagger。
目录
一. 加入依赖JAR文件
二. 配置
三. 标注你的接口
四. 访问接口文档
五. 核心API
六. 示例程序下载
一. 加入依赖JAR文件
maven：<dependency><groupId>com.github.3cpj</groupId><artifactId>cpj-swagger</artifactId><version>1.2.1</version></dependency>
二. 配置
1. 选择使用方式
您可以通过三种方式来使用cpj-swagger。
与strut2集成
如果您的web项目是基于strut2的，您可以在您的strut2配置文件中加入如下代码来快速集成cpj-swagger：
<constant name="struts.enable.DynamicMethodInvocation" value="true" /><constant name="struts.devMode" value="true" /><package name="api" namespace="/api" extends="struts-default" ><action name="*" class="com.cpj.swagger.support.struts2.ApiAction" method="{0}"></action></package>
与spring mvc集成
如果您的web项目是基于spring mvc的，您可以在您的spring mvc配置文件中加入如下代码来快速集成cpj-swagger：
<context:component-scan base-package="com.cpj.swagger.support.springmvc"><context:include-filter type="annotation" expression="org.springframework.stereotype.Controller"/></context:component-scan>
与servlet集成
如果您的web项目是基于servlet的，您可以在您的web.xml配置文件中加入如下代码来快速集成cpj-swagger：
<servlet><servlet-name>apiServlet</servlet-name><servlet-class>com.cpj.swagger.support.servlet.ApiServlet</servlet-class></servlet><servlet-mapping><servlet-name>apiServlet</servlet-name><url-pattern>/api/*</url-pattern></servlet-mapping>
2. 修改配置项
您需要在项目的源文件目录下添加一个swagger.properties文件，并加入以下配置项：
packageToScan=com.cpj.swagger.actionapiDescription=Swagger DemoapiTitle=Swagger DemoapiVersion=1.0.0teamOfService=devMode=true
cpj-swagger的配置信息都必须写在swagger.properties文件里面。具体的配置项及其说明如下：
三. 标注你的接口
接下来需要用cpj-swagger提供的注解来标明你的接口，下面以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/您的项目名/api/index
五. 核心API
1. 注解 @com.cpj.swagger.annotation.APIs
该注解放在一个类上面，用来表明类中包含作为HTTP接口的方法（被注解@com.cpj.swagger.annotation.API标注了的方法）。 该注解的value用来设置接口的前缀，这和struts2的命名空间很像。使用示例如下：
@APIs("/demo")public class DemoController {}
2. 注解 @com.cpj.swagger.annotation.API
该注解放在一个方法上面，用来表明方法是HTTP接口方法，注解的属性说明如下：
value
与注解@com.cpj.swagger.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的in属性必须为formData，但是in为path、header时Param不用遵循此规则。
3. 注解 @com.cpj.swagger.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.cpj.swagger.annotation.Param的属性说明如下：
name
参数名
in
输入参数类型，可取如下值：
query - 参数拼接到url中body - 参数直接放入请求体中path - restful风格的参数传递header - 参数放在请求头中formData - 参数通过form表单提交
特别说明：
当前请求方式为POST的时候，默认值为formData请求方式为非POST的时候，默认值为query
type
数据类型, 与format一起指定请求参数的数据类型。type和format的可选值如下：
format
数据格式，type一起指定请求参数的数据类型。
description
参数说明
required
是否是必须参数， 默认是false
六. 示例程序下载
spring mvc
struts2
servlet
七. 与struts2整合项目演示
进入git命令行，输入命令下载代码
git clone /3cpj/swagger-demo-struts2.git
然后进入项目文件夹内
cd swagger-demo-struts2/
把项目转成eclipse项目
mvn eclipse:eclipse
导入eclipse之后发布项目到tomcat，然后启动项目，访问地址：http://localhost:8080/swagger-demo-struts2/api/index
运行效果：
整个接口的参数一目了然。
