cpj-swagger

原文地址：https://github.com/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.action
apiDescription=Swagger Demo
apiTitle=Swagger Demo
apiVersion=1.0.0
teamOfService=www.cpj.com
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 https://github.com/3cpj/swagger-demo-struts2.git

然后进入项目文件夹内

cd swagger-demo-struts2/

把项目转成eclipse项目

mvn eclipse:eclipse 

导入eclipse之后发布项目到tomcat，然后启动项目，访问地址：http://localhost:8080/swagger-demo-struts2/api/index

运行效果：

整个接口的参数一目了然。