cpj-swagger分别整合struts2、spring mvc、servlet

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文件里面。具体的配置项及其说明如下：

键	说明
apiFile	扫描生成json文件的存放路径
packageToScan	扫描的包
apiDescription	接口文档描述
apiTitle	接口文档标题
apiVersion	接口版本
teamOfService	服务团队
apiHost	接口主机地址
apiBasePath	接口基路径
devMode	是否启用开发模式，如果开启则每次获取接口文档的时候都会扫描类
suffix	接口请求地址后缀，如.action

三. 标注你的接口

接下来需要用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 的可选值如下：

通用名	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.

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

运行效果：

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