Swagger+Spring mvc生成Restful接口文档

简介

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>

[/code][/code]

添加配置

添加一个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 serializationSerializationConfig 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);
}

@Overrideprotected 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>

[/code][/code]我们再来看看效果:



来源： http://www.cnblogs.com/yuananyun/p/4993426.html

来自为知笔记(Wiz)