Swagger+ springfox +Spring mvc

簡介

Swagger 是一個規范和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。
這一次我將從零開始搭建一個工程來演示如何在Spring mvc中整合Swagger生成Restful接口文檔。

新建工程

我們新建一個Maven工程，並添加Web Facet，工程結構如下圖所示：

添加Maven依賴

 <properties> <spring.version>4.1.7.RELEASE</spring.version> <version.jackson>2.4.4</version.jackson> <swagger.version>2.2.2</swagger.version> </properties> <dependencies> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-webmvc</artifactId> <version>${spring.version}</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-core</artifactId> <version>${spring.version}</version> </dependency> <dependency> <groupId>com.mangofactory</groupId> <artifactId>swagger-springmvc</artifactId> <version>1.0.2</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-annotations</artifactId> <version>${version.jackson}</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>${version.jackson}</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-core</artifactId> <version>${version.jackson}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>${swagger.version}</version> </dependency> <dependency> <groupId>javax.servlet</groupId> <artifactId>javax.servlet-api</artifactId> <version>3.1.0</version> </dependency> <!--petstore是官方的一個demo，加入此依賴是為了稍后參考接口描述的編寫--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-petstore</artifactId> <version>${swagger.version}</version> </dependency> </dependencies>

添加配置

添加一個ApplicationInitializer類，用於配置DispatchServlet啟動：

在工程中的resources文件夾下新建一個spring的文件夾，並新建一個dispatcher-servlet.xml的spring mvc配置文件，添加如下內容：

添加一個SwaggerConfig類，用於配置Swagger接口的說明：

新建Controller

新建一個GroupController,並編寫測試方法：

    package yay.apidoc.controller; import io.swagger.annotations.*; import org.springframework.stereotype.Controller; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import yay.apidoc.model.UamGroup; import java.util.LinkedList; import java.util.List; /** * Created by yuananyun on 2015/11/23. */ @Controller @RequestMapping(value = "/group", produces = {"application/json;charset=UTF-8"}) @Api(value = "/group", description = "群組的相關操作") public class GroupController { @RequestMapping(value = "addGroup", method = RequestMethod.PUT) @ApiOperation(notes = "addGroup", httpMethod = "POST", value = "添加一個新的群組") @ApiResponses(value = {@ApiResponse(code = 405, message = "invalid input")}) public UamGroup addGroup(@ApiParam(required = true, value = "group data") @RequestBody UamGroup group) { return group; } @RequestMapping(value = "getAccessibleGroups", method = RequestMethod.GET) @ApiOperation(notes = "getAccessibleGroups", httpMethod = "GET", value = "獲取我可以訪問的群組的列表") public List<UamGroup> getAccessibleGroups() { UamGroup group1 = new UamGroup(); group1.setGroupId("1"); group1.setName("testGroup1"); UamGroup group2 = new UamGroup(); group2.setGroupId("2"); group2.setName("testGroup2"); List<UamGroup> groupList = new LinkedList<UamGroup>(); groupList.add(group1); groupList.add(group2); return groupList; } }

其中UamGroup的定義如下：

    package yay.apidoc.model;
    import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; /** * 群組 */ @ApiModel public class UamGroup { /** * 編號 */ @ApiModelProperty(value = "群組的Id", required = true) private String groupId; /** * 名稱 */ @ApiModelProperty(value = "群組的名稱", required = true) private String name; /** * 群組圖標 */ @ApiModelProperty(value = "群組的頭像", required = false) private String icon; public String getGroupId() { return groupId; } public void setGroupId(String groupId) { this.groupId = groupId; } public String getName() { return name; } public void setName(String name) { this.name = name; } public String getIcon() { return icon; } public void setIcon(String icon) { this.icon = icon; } }

好，目前為止我們的代碼已經編寫完成，整個工程的目錄結構如下：

為了讓Swagger能夠掃描Spring mvc中定義的Controller，我們需要在mvc的配置文件里面定義掃描的路徑和相關的bean：

添加Swagger ui

在GitHub上下載SwaggerUI項目，將dist下所有內容拷貝到本地項目apidoc/web下面，結果目錄如下圖所示：

打開目錄下的index.html文件，找到代碼片段url = "http://petstore.swagger.io/v2/swagger.json";修改為“/apidoc/v2/api-docs”。
為了讓網頁顯示中文，我們可以取消注釋以下腳本：

為了能夠訪問index.html頁面，我們在dispatcher-servlet.xml中添加如下配置：

 <!-- Enables swgger ui--> <mvc:resources mapping="*.html" location="/"/> <mvc:resources mapping="/**" location="/"/>

好，現在我們啟動tomcat來看看效果：

解決中文亂碼

可以看到，我們寫在方法上說明居然成了亂碼，為了解決這個問題，我們新建一個轉換類：

    package yay.apidoc.converter; import com.fasterxml.jackson.annotation.JsonInclude; import com.fasterxml.jackson.databind.*; import org.springframework.http.HttpInputMessage; import org.springframework.http.converter.HttpMessageNotReadableException; import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter; import java.io.IOException; import java.text.SimpleDateFormat; /** * Created by yuananyun on 2015/11/23. */ public class MappingJacksonHttpMessageConverterEx extends MappingJackson2HttpMessageConverter { private ObjectMapper objectMapper = new ObjectMapper(); public MappingJacksonHttpMessageConverterEx() { super(); DeserializationConfig deserializationConfig = objectMapper.getDeserializationConfig() .without(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES); objectMapper.setConfig(deserializationConfig); // Configure serialization SerializationConfig serializationConfig = objectMapper.getSerializationConfig() .without(SerializationFeature.FAIL_ON_EMPTY_BEANS); //serializationConfig.withDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss")); objectMapper.setConfig(serializationConfig); objectMapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss")); objectMapper.setSerializationInclusion(JsonInclude.Include.NON_NULL); // objectMapper.configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, true); objectMapper.configure(SerializationFeature.ORDER_MAP_ENTRIES_BY_KEYS,true); setObjectMapper(objectMapper); } @Override protected Object readInternal(Class<?> clazz, HttpInputMessage inputMessage) throws IOException, HttpMessageNotReadableException { JavaType javaType = getJavaType(null, clazz); return this.objectMapper.readValue(inputMessage.getBody(), javaType); } }

然后修改dispatcher-servlet.xml中的mvc:annotation-driven配置節：

 <!-- Standard xml based mvc config--> <mvc:annotation-driven> <mvc:message-converters> <bean class="org.springframework.http.converter.StringHttpMessageConverter"> <property name="supportedMediaTypes"> <list> <value>text/html;charset=UTF-8</value> </list> </property> </bean> <bean class="yay.apidoc.converter.MappingJacksonHttpMessageConverterEx"/> <bean class="org.springframework.http.converter.ResourceHttpMessageConverter"/> </mvc:message-converters> </mvc:annotation-driven>

我們再來看看效果:

最后提供本次源碼下載：
http://files.cnblogs.com/files/yuananyun/Swagger%E4%B8%8ESpring%E7%BB%93%E5%90%88%E7%94%9F%E6%88%90Restful%E6%8E%A5%E5%8F%A3%E6%96%87%E6%A1%A3.rar