Spring MVC中使用Swagger生成API文档

实际项目中非常需要写文档,提高Java服务端和Web前端以及移动端的对接效率。 听说Swagger这个工具,还不错,就网上找了些资料,自己实践了下。 一:Swagger介绍Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目实现了与SpingMVC框架的无缝集成功能,方便生成spring restful风格的接口文档,同时swagger-ui还可以测试spring restful风格的接口功能。 官方网站为:http://swagger.io/ 中文网站:http://www.sosoapi.com

二:Swagger与Spring MVC集成步骤

1.Maven关键配置

<dependency>
            <groupId>com.mangofactory</groupId>
            <artifactId>swagger-springmvc</artifactId>
            <version>1.0.2</version>
        </dependency>

 <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-webmvc</artifactId>
        <version>4.1.6.RELEASE</version>
      </dependency>

2. 插件配置 CustomJavaPluginConfig 3.复制swagger的相关js等静态资源到webapp目录。 swagger-ui.js之类的。 我copy过一次,但是有问题,最后从网上下载了一个项目,可以直接用的那种。 然后自己再逐步改造。 4.启动项目 http://localhost:8080/

三、常见swagger注解一览与使用最常用的5个注解 @Api:修饰整个类,描述Controller的作用@ApiOperation:描述一个类的一个方法,或者说一个接口@ApiParam:单个参数描述 @ApiModel:用对象来接收参数@ApiProperty:用对象接收参数时,描述对象的一个字段

其它若干@ApiResponse:HTTP响应其中1个描述@ApiResponses:HTTP响应整体描述 @ApiClass@ApiError@ApiErrors @ApiParamImplicit@ApiParamsImplicit 四、关键代码和实际例子 例子1:

@ApiOperation(value = "获得用户列表", notes = "列表信息", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseBody
    @RequestMapping(value = "list", method = RequestMethod.POST)
    public Result<User> list(
            @ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId,
            @ApiParam(value = "token", required = true) @RequestParam String token) {
        Result<User> result = new Result<User>();
        User user = new User();
        result.setData(user);
        return result;
    }

@ApiParam(value = “token”, required = true) @RequestParam String tokenWeb前端/移动端HTTP请求方式:直接把参数附带到URL后面,或者用AJAX方法,表单提交。 例子2:

@ApiOperation(value = "update用户", notes = ")", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseBody
    @RequestMapping(value = "update", method = RequestMethod.GET/*,produces = MediaType.APPLICATION_FORM_URLENCODED_VALUE*/)
    public Result<String> update(User user) {
        String u = findUser(user);
        System.out.println(u);
        return null;
    }

当参数太多的时候,需要定义太多的参数,排版看起来很不舒服。这个时候,可以使用对象来接收。@ApiModel(value = “用户对象”,description=”user2″) public class User extends CommonParam{ }Web前端/移动端HTTP请求方式:直接把参数附带到URL后面,或者用AJAX方法,表单提交。 这里面存在一个小问题,当后端用对象User来接收参数的时候,Swagger自带的工具是这样的:

这种形式,并不是表单提交,或者把参数附加到URL的后面。我们只能手动构造URL,附带参数去提交。如果需要测试的话! 例子3:

public Result<String> add(@RequestBody User user) {
        String u = findUser(user);
        System.out.println(u);
        return null;
    }

Web前端/移动端HTTP请求方式:必须把参数,放到request请求的body中去。 后端不能直接用request.getParam(“token”)这种。 获得request body中的数据,手动转换成目标数据。 String charReader(HttpServletRequest request) throws IOException { BufferedReader br = request.getReader(); String str, wholeStr = “”; while ((str = br.readLine()) != null) { wholeStr += str; } return wholeStr; } 个人推荐1.参数不多的时候,用例子1,用@ApiParam注解生成文档。 swagger可视化界面,可以直接设置参数,发送请求来测试2.参数比较多的时候,用例子2,用对象来接收参数,在对象里针对每个字段,@ApiModelProperty注解生成文档。 swagger可视化界面,可以直接设置参数,但是无法接收到。 因此,推荐使用其它HTTP请求或POST模拟工具,发送请求,模拟测试。 不推荐例子3,不通用,局限性比较大。

五、若干截图

六、源代码

package cn.fansunion.swagger.serverapi.controller;

import org.springframework.http.MediaType;
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 org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;

import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;
import com.wordnik.swagger.annotations.ApiParam;

/**
 * 小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119
 * 博客:http://blog.csdn.net/fansunion
 *
 */
@Api(value = "user", description = "用户管理", produces = MediaType.APPLICATION_JSON_VALUE)
@Controller
@RequestMapping("user")
public class UserController {

	// 列出某个类目的所有规格
	@ApiOperation(value = "获得用户列表", notes = "列表信息", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
	@ResponseBody
	@RequestMapping(value = "list", method = RequestMethod.POST)
	public Result<User> list(
			@ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId,
			@ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId2,
			@ApiParam(value = "token", required = true) @RequestParam String token) {
		Result<User> result = new Result<User>();
		User user = new User();
		result.setData(user);
		return result;
	}

	@ApiOperation(value = "添加用户", notes = "获取商品信息(用于数据同步)", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
	@ResponseBody
	@RequestMapping(value = "add", method = RequestMethod.POST)
	// @RequestBody只能有1个
	// 使用了@RequestBody,不能在拦截器中,获得流中的数据,再json转换,拦截器中,也不清楚数据的类型,无法转换成java对象
	// 只能手动调用方法
	public Result<String> add(@RequestBody User user) {
		String u = findUser(user);
		System.out.println(u);
		return null;
	}

	@ApiOperation(value = "update用户", notes = "获取商品信息(用于数据同步)", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
	@ResponseBody
	@RequestMapping(value = "update", method = RequestMethod.GET)
	public Result<String> update(User user) {
		String u = findUser(user);
		System.out.println(u);
		return null;
	}

	private String findUser(User user) {
		String token = user.getToken();
		return token;
	}
}
package cn.fansunion.swagger.serverapi.controller;

import com.wordnik.swagger.annotations.ApiModel;
import com.wordnik.swagger.annotations.ApiModelProperty;

/**
 * 小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119
 * 博客:http://blog.csdn.net/fansunion
 *
 */
@ApiModel(value = "用户对象", description = "user2")
public class User extends CommonParam {

	@ApiModelProperty(value = "商品信息", required = true)
	private String name;
	@ApiModelProperty(value = "密码", required = true)
	private String password;

	@ApiModelProperty(value = "性别")
	private Integer sex;
	@ApiModelProperty(value = "密码", required = true)
	private String token;

	public String getToken() {
		return token;
	}

	public void setToken(String token) {
		this.token = token;
	}

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public String getPassword() {
		return password;
	}

	public void setPassword(String password) {
		this.password = password;
	}

	public Integer getSex() {
		return sex;
	}

	public void setSex(Integer sex) {
		this.sex = sex;
	}

}
package cn.fansunion.swagger.serverapi.swagger;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.paths.SwaggerPathProvider;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;

@Configuration
@EnableWebMvc
@EnableSwagger
public class CustomJavaPluginConfig extends WebMvcConfigurerAdapter {

	private SpringSwaggerConfig springSwaggerConfig;

	@Autowired
	public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
		this.springSwaggerConfig = springSwaggerConfig;
	}

	/**
	 * 链式编程 来定制API样式 后续会加上分组信息
	 * 
	 * @return
	 */
	@Bean
	public SwaggerSpringMvcPlugin customImplementation() {
		return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
				.apiInfo(apiInfo()).includePatterns(".*")
				.useDefaultResponseMessages(false)
			//	.pathProvider(new GtPaths())
				.apiVersion("0.1").swaggerGroup("user");

	}

	private ApiInfo apiInfo() {
		ApiInfo apiInfo = new ApiInfo("小雷移动端API接口平台",
				"提供详细的后台所有Restful接口", "http://blog.csdn.net/FansUnion",
				"FansUnion@qq.com", "小雷博客", "http://blog.csdn.net/FansUnion");
		return apiInfo;
	}

	@Override
	public void configureDefaultServletHandling(
			DefaultServletHandlerConfigurer configurer) {
		configurer.enable();
	}

	class GtPaths extends SwaggerPathProvider {

		@Override
		protected String applicationPath() {
			return "/restapi";
		}

		@Override
		protected String getDocumentationPath() {
			return "/restapi";
		}
	}

}

七、项目下载地址 http://git.oschina.net/fansunion/swagger-server-api/tree/master/ 八、参考资料/content/2509249.html/content/4604058.htmlhttp://www.cnblogs.com/h9527/p/5506956.html/content/4209073.html

文章来源:http://www.lai18.com/content/24605834.html

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏李蔚蓬的专栏

Install Node.js

安装的话其实很容易,只要登陆上官网:https://nodejs.org/en/download/ 如下图:

25750
来自专栏李蔚蓬的专栏

广播的最佳实践——实现强制下线功能(Android_Broadcast)

其一,用于辅助统筹管理本项目的所有活动。调用ActivityCollector类的方法,如类中的onCreate和onDestroy方法,所有从父类派生出去的子...

16730
来自专栏李蔚蓬的专栏

小结:greenDAO和LitePal的区别

1. greenDAO的version等数据库属性设置都是在对应的模型类里面完成的,以Java class的属性变量的形式存储;而LitePal是在另外的一个x...

38910
来自专栏李蔚蓬的专栏

Android实战_note1(MyMirror_一款小型摄像处理的App)

1.1 Activity.java全文: 注意代码中的注释,其中 handler.sendEmptyMessageDelayed(1,3000);...

10920
来自专栏Hongten

python开发_dbm_键值对存储_完整_博主推荐

============================================

13150
来自专栏李蔚蓬的专栏

Content Provider 之 最终弹 实战体验跨程序数据共享(结合SQLiteDemo)

本模块共有四篇文章,参考郭神的《第一行代码》,对Content Provider的学习做一个详细的笔记,大家可以一起交流一下:

13640
来自专栏Danny的专栏

SLF4J和Logback日志框架详解

SLF4J是一套简单的日志外观模式的Java API,帮助在项目部署时对接各种日志实现。

27840
来自专栏李蔚蓬的专栏

跨程序共享数据——Content Provider 之 ContentResolver基本用法 & 一个读取系统联系人的Demo

本模块共有四篇文章,参考郭神的《第一行代码》,对Content Provider的学习做一个详细的笔记,大家可以一起交流一下:

17620
来自专栏李蔚蓬的专栏

java.lang.IndexOutOfBoundsException and drawPosText

郁闷。。报错的原因是数组超范围了。。 还以为是for语句写错了,看了半天。。。没错啊。。。

12620
来自专栏Hongten

python开发_tkinter_图片操作

在java的swing中,我们可以找到一些有关图片的操作,对于python的tkinter类似,也有对于图片的相关操作

12820

扫码关注云+社区

领取腾讯云代金券

年度创作总结 领取年终奖励