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

運行效果：

 

 

 

 整個接口的參數一目了然。