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>
添加配置
添加一个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>
我们再来看看效果:
Swagger+Spring mvc生成Restful接口文档的更多相关文章
- Swagger: 一个restful接口文档在线生成+功能测试软件
一.什么是 Swagger? Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件.Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 ...
- Spring Boot 集成 Swagger 生成 RESTful API 文档
原文链接: Spring Boot 集成 Swagger 生成 RESTful API 文档 简介 Swagger 官网是这么描述它的:The Best APIs are Built with Swa ...
- spring boot使用swagger生成api接口文档
前言 在之前的文章中,使用mybatis-plus生成了对应的包,在此基础上,我们针对项目的api接口,添加swagger配置和注解,生成swagger接口文档 具体可以查看本站spring boot ...
- Spring Boot学习笔记 - 整合Swagger2自动生成RESTful API文档
1.添加Swagger2依赖 在pom.xml中加入Swagger2的依赖 <!--swagger2--> <dependency> <groupId>io.spr ...
- springboot项目利用Swagger2生成在线接口文档
Swagger简介. Swagger2是一款restful接口文档在线生成和在线调试工具.很多项目团队利用Swagger自动生成接口文档,保证接口文档和代码同步更新.在线调试.简单地说,你可以利用这个 ...
- Spring MVC学习总结(9)——Spring MVC整合swagger自动生成api接口文档
Swagger 号称:世界最流行的API框架,官网:http://swagger.io/,Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总 ...
- Spring Boot 系列(七)Swagger2-生成RESTful接口文档
Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参数和模型紧密集成到服 ...
- 使用Swagger生成简单接口文档
使用swagger通过简单的配置可以生成简单的接口文档: 依赖包: // Swagger2 compile 'io.springfox:springfox-swagger2:2.8.0' compil ...
- Spring Boot 集成Swagger2生成RESTful API文档
Swagger2可以在写代码的同时生成对应的RESTful API文档,方便开发人员参考,另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API. 使用Spring Boot可 ...
随机推荐
- Spring 事务管理 01 ——
目录: 参考: 1.Spring 事务管理高级应用难点剖析: 第 1 部分
- uva 1151(最小生成树,枚举子集)
题意:平面上有n个点(1<=N<=1000),你的任务是让所有n个点连通,为此,你可以新建一些边,费用等于两个端点的欧几里得距离的平方.另外还有q(0<=q<=8)个套餐,可以 ...
- Topcoder SRM583 DIV 2 250
#include <string> #include <iostream> using namespace std; class SwappingDigits { public ...
- iOS开发多线程篇—NSOperation基本操作
iOS开发多线程篇—NSOperation基本操作 一.并发数 (1)并发数:同时执⾏行的任务数.比如,同时开3个线程执行3个任务,并发数就是3 (2)最大并发数:同一时间最多只能执行的任务的个数. ...
- js里function的apply vs. bind vs. call
js里除了直接调用obj.func()之外,还提供了另外3种调用方式:apply.bind.call,都在function的原型里.这3种方法的异同在stackoverflow的这个答案里说的最清楚, ...
- CodeForces 686C-Robbers' watch
题意: 一个电子手表的示数是7进制的,现在告诉你一天有多少小时和一小时有多少分钟,问你一天里有多少个时刻,这个表上显示的数字各不相同. 分析: 先找出表上有多少位数字,再按位dfs,看最后得到的数是否 ...
- 大数运算Swift
前几天开始,打算用Swift写大数的运算,加法跟乘法都已经写好了,写减法发现,真是难,感觉有可能是我的想法不对?不不不我相信我的逻辑. 首先把数字分成小数部分跟整数部分,再遍历一下,识别当前的结果,是 ...
- dij单源最短路纯模板
#include <iostream> #include <cstdio> #include <cstdlib> #include <algorithm> ...
- OD调试篇6--对一些真正的小程序进行一点点的修改
先打开这个程序看看,提醒你这是一个未注册版本的软件.会发现只能添加4个联系人,这显然是我不想看见的,于是我要对这个程序进行一些修改,嘿嘿... 通过OD载入这个程序 有一些(SEH)也就是异常,我们可 ...
- 上载android应用的apk文件变成了zip-网下转载的解决方案
下载android应用的apk文件变成了zip--网上转载的解决方案 下载android应用的apk文件变成了zip--网上转载的解决方案 解决方案一. 最近把开发的android应用放在公司网站上, ...