Swagger+ springfox +Spring mvc
阿新 • • 發佈：2017-09-20
XML .com med -type port import eth keys 服務器 簡介
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%
Swagger+ springfox +Spring mvc