开发者社区> 贾志刚> 正文
阿里云
为了无法计算的价值
打开APP
阿里云APP内打开

Spring3 MVC中使用Swagger生成API文档

简介: Spring3 MVC中使用Swagger生成API文档 一:Swagger介绍 Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目 实现了与SpingMVC框架的无缝集成功能,方便生成spring restful风格的接口文档, 同时swagger-ui还可以测试spring restful风格的接口功能。
+关注继续查看

Spring3 MVC中使用Swagger生成API文档

一:Swagger介绍

Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目

实现了与SpingMVC框架的无缝集成功能,方便生成spring restful风格的接口文档,

同时swagger-ui还可以测试spring restful风格的接口功能。其官方网站为:

http://swagger.io/

二:Swagger集成Spring3 MVC步骤

Swagger集成springMVC步骤大致只有如下几步:

1.在pom.xml文件中添加swagger相关的依赖

                <!-- swagger API document -->
		<dependency>
			<groupId>com.mangofactory</groupId>
			<artifactId>swagger-springmvc</artifactId>
			<version>0.6.5</version>
		</dependency>

2.创建classpath路径下创建一个swagger.properties, 添加如下内容:

documentation.services.version=1.0

documentation.services.basePath=http://localhost:8080/yourcontextpath

3.在springMVC的main-servlet.xml文件添加如下配置

	<context:property-placeholder location="classpath:swagger.properties" />
	<bean id="documentationConfig" class="com.mangofactory.swagger.configuration.DocumentationConfig" />

4.重新打包部署你的项目到WEB服务器,访问地址

http://localhost:8080/your-contextpath /api-docs即可看到注解生成的API说明

三:常见swagger注解一览与使用

APIs.@Api

@ApiClass

@ApiError

@ApiErrors

@ApiOperation

@ApiParam

@ApiParamImplicit

@ApiParamsImplicit

@ApiProperty

@ApiResponse

@ApiResponses

@ApiModel

在代码中使用例子:

import java.util.HashMap;
import java.util.Map;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Controller;
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.ApiOperation;

@Controller
@RequestMapping("/api/swagger")
public class SwaggerDemoController {
	private static final Logger logger = LoggerFactory.getLogger(SwaggerDemoController.class);
	
	@ApiOperation(value = "query api basic information")
	@RequestMapping(value = "/info", method = RequestMethod.GET)
	@ResponseBody
	public Map<String, String> queryAPIInfo() {
		logger.info("查询更新新版本号");
		Map<String, String> map = new HashMap<String, String>();
		map.put("language", "Java");
		map.put("format", "JSON");
		map.put("tools", "swagger");
		map.put("version", "1.0");
		return map;
	}
	
	@ApiOperation(value = "query data with parameters")
	@RequestMapping(value = "/data", method = RequestMethod.GET)
	@ResponseBody
	public Map<String, String> queryData(@RequestParam String words) {
		logger.info("查询更新新版本号");
		Map<String, String> map = new HashMap<String, String>();
		map.put("keyword", words);
		map.put("data", "this is demo data");
		return map;
	}
}

四:运行swagger-ui测试接口

下载swagger-ui的最新版本到本地,改名为swagger-ui,把dist下面的部署到tomcat

或者任何WEB服务器上,启动后访问如下地址: http://localhost:8080/swagger-ui

注意把swagger-ui中的index.html中的http://petstore.swagger.io/v2/swagger.json改为

http://localhost:8080/your-contextpath /api-docs保存,然后在启动WEB服务器,

显示如下:

展开输入参数以后,点击【try it out】即可测试接口,查看返回数据。
注意:加上之后启动报Bean not found mapping之类的错误,请在对应

xml文件中加上如下的配置:

<context:annotation-config />
<mvc:default-servlet-handler />

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
Apache HttpClient调用Spring3 MVC Restful Web API演示
Apache HttpClient调用Spring3 MVC Restful Web API演示 使用HttpRequest提交数据与HttpResponse响应客户端都是支持json数据格式,实现在HTTP Client端调用Spring3 MVC Restful API例子。
668 0
在Spring3 MVC中五步配置集成注解方式Hibernate3
最近在搞一个WEB项目,以前在公司做项目用的都是JPA做ORM持久层,这次这个项目是我自己接的,我决定改一下,用Hibernate3来做ORM持久层、于是我网上搜索了Hibernate3怎么配置集成到Spring3 MVC上,发现千奇百怪,而且很多都是不是基于注解方式配置,显然那些文字上面的配置方式已经跟如今的Hibernate3注解支持方式脱节了,于是我决定自己搞一把,首先说一下网上那些配置方式的不好的地方,很多文章都提到要jdbc.properties文件与Hibernate config文件,其实是如今基于注解,完全没有必要。
957 0
Spring3 MVC请求参数获取的几种场景
访问/aaa/bbb所对应的@Controller @RequestMapping("/aaa")//类级别,可以不需要,如果要了,下面所有的请求路径前都需要加入/aaa public class DefaultController{ @Reque...
611 0
记录一次让我吐血的spring3 MVC HTTP406 Json转换错误
朋友给了我点东西,我就想把它用Maven重新搞一下,不要ant啦。 看到它的spring dispatch servlet url mapping 是根据*.do来做的 我不习惯就为了*.html然后其它都搞了过来,tomcat一跑发现一个 第一个错误: 于是我在对应的sprin...
760 0
【转】spring3 MVC实战,手工搭建Spring3项目demo
更新:这几天对spring3的理解又进了一步,今天抽空把这篇文章中的错误和不当之处做了修改。 最近的项目在用Spring3,涉及到了基于注解的MVC,事务管理,与hibernate的整合开发等内容,我打算写一个系列出来,记录下这个痛苦但又充满成就感的过程----网上实在太难找能让新手快速理解掌握的文章了 这篇文章专门针对使用Spring3进行开发的新手,高手就请绕道吧,也欢迎拍个砖再走.
1018 0
Spring3 MVC 集成Velocity中文支持
Maven中加上Velocity的依赖如下: org.apache.velocity velocity 1.5 velocity-tools velocity-tools-generic 1.
540 0
基于Spring3 MVC实现基于HTML form表单文件上传
基于Spring3 MVC实现基于form表单文件上传 一:杂项准备 环境搭建参考这里-http://blog.csdn.net/jia20003/article/details/8471169 二:前台页面 根据RFC1867,只要在提交form表单中声明提交方法为POST,enctype属 性声明为multipart/form-data, action声明到要提交的url即可。
823 0
基于Asp.Net Mvc开发的个人博客系统
一个基于Mvc 5构建的简单、代码层级分明的开源个人博客系统。前端美观大气、后台采用RightControl .NET通用角色权限系统,开发简单、效率高。网站配置采用XML配置,灵活可以根据自己是需求进行个性化配置。系统功能完备,完全可以满足需求,基本不用二次开发,非常使用程序员的个人博客。
0 0
+关注
贾志刚
2004毕业于山东大学齐鲁软件学院,软件工程专业。主要专注于图像处理算法学习与研究,计算机视觉技术开发应用,深度学习在计算机视觉领域应用。两本书籍《Java数字图像处理-编程技巧与应用实践》、《OpenCV On Android编程实践》作者
文章
问答
文章排行榜
最热
最新
相关电子书
更多
Java Spring Boot开发实战系列课程【第7讲】:Spring Boot 2.0安全机制与MVC身份验证实战(Java面试题)
立即下载
Java Spring Boot开发实战系列课程【第15讲】:Spring Boot 2.0 API与Spring REST Docs实战
立即下载
Spring Boot2.0实战Redis分布式缓存
立即下载