swagger和springmvc结合自动生成api接口文档

原创 2016年11月01日 17:35:50

简介:

号称:世界最流行的API框架

官网:http://swagger.io/

是什么:Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

使用工具:eclipse,jdk7,maven,spring

使用方法:

首先你得有自己的一个能访问的api代码,一个简单的demo就可以,然后我们开始添加代码

1.maven依赖:

<!-- swagger-springmvc dependencies -->
	    <dependency>
	        <groupId>com.google.guava</groupId>
	        <artifactId>guava</artifactId>
	        <version>15.0</version>
	    </dependency>
	    <dependency>
	        <groupId>com.fasterxml.jackson.core</groupId>
	        <artifactId>jackson-annotations</artifactId>
	        <version>2.4.4</version>
	    </dependency>
	    <dependency>
	        <groupId>com.fasterxml.jackson.core</groupId>
	        <artifactId>jackson-databind</artifactId>
	        <version>2.4.4</version>
	    </dependency>
	    <dependency>
	        <groupId>com.fasterxml.jackson.core</groupId>
	        <artifactId>jackson-core</artifactId>
	        <version>2.4.4</version>
	    </dependency>
	    <dependency>
	        <groupId>com.fasterxml</groupId>
	        <artifactId>classmate</artifactId>
	        <version>1.1.0</version>
	    </dependency>
	    <!-- CORS配置,为了让别的机器访问本机的swagger接口文档服务 -->
	    <dependency>
		    <groupId>com.thetransactioncompany</groupId>
		    <artifactId>cors-filter</artifactId>
	    <version>2.5</version>
2.我们在代码中添加SwaggerConfig配置类:

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.EnableWebMvc;

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

@Configuration
@EnableSwagger
@EnableWebMvc
public class SwaggerConfig {
	private SpringSwaggerConfig springSwaggerConfig;

	/**
	 * Required to autowire SpringSwaggerConfig
	 */
	@Autowired
	public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
		this.springSwaggerConfig = springSwaggerConfig;
	}

	/**
	 * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
	 * framework - allowing for multiple swagger groups i.e. same code base
	 * multiple swagger resource listings.
	 */
	@Bean
	public SwaggerSpringMvcPlugin customImplementation() {
		return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo()).includePatterns(".*?");
	}

	private ApiInfo apiInfo() {
		ApiInfo apiInfo = new ApiInfo(
				"ums接口文档",
				"这里是所有的ums接口,里边含有说明,请自行测试",
				"My Apps API terms of service",
				"My Apps API Contact Email",
				"My Apps API Licence Type",
				"My Apps API License URL");
		return apiInfo;
	}
}
这里得有一个注意的地方, @EnableWebMvc注解,在网上的大部分代码中都没有这个注解,小编做的时候也遇到了很大的麻烦,会报SwaggerConfig类不能自动装载,加上了这个就好了,具体用法大家想了解的自行查找。

3.springMVC配置文件中加上这段代码:

<!-- swagger测试 :注入SpringSwaggerConfig-->
	<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
4.添加测试类:

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import com.wordnik.swagger.annotations.ApiOperation;
import com.wordnik.swagger.annotations.ApiParam;
@RequestMapping(value = "/rs/swagger")
@Controller
public class SwaggerTestController {
	/**
	 * 根据用户名获取用户对象
	 * @param name
	 * @return
	 */
	@RequestMapping(value="/name/{name}", method = RequestMethod.GET)
	@ResponseBody
	@ApiOperation(value = "根据用户名获", httpMethod = "GET", response = UserDTO.class, notes = "根据用户名获取用户对象")
	public UserDTO getUserByName(@ApiParam(required = true, name = "name", value = "用户名") @PathVariable String name) throws Exception{
	    UserDTO ucUser = new UserDTO();
	    ucUser.setLoginName("测试账号");
        return ucUser;
	}
}
UserDTO这个类大家可自行定义。

经过这几步之后你就可以看到返回的数据了,但是是json的格式,下面我们来配置swagger:

1.大家首先去官网下载压缩包,解压之后将里边的dist文件直接复制到项目中的src下边的main下的webapp中,改名为apidocs(为了直观),之后的效果是这样的:



2.打开apidocs中的index.html文件,搜索http://petstore.swagger.io/v2/swagger.json,修改格式为http://ip:端口/项目名/api-docs

3.tomcat:run启动tomcat项目,或者放到本地的tomcat中,在浏览器中输入访问地址即可访问到swagger主页:我的主页是这样的(汉化之后):


4.这时候遇到了一个问题:本机可以访问但是别的机器不能访问,这样我们就失去了这个技术的初衷,别的机器访问的时候回报错:原因是cors跨域限制,这时候我们在web.xml中假如一段代码即可:


<!-- cors配置 -->
	<filter>
		<filter-name>CORS</filter-name>
		<filter-class>com.thetransactioncompany.cors.CORSFilter</filter-class>
		<init-param>
			<param-name>cors.allowOrigin</param-name>
			<param-value>*</param-value>
		</init-param>
		<init-param>
			<param-name>cors.supportedMethods</param-name>
			<param-value>GET, POST, HEAD, PUT, DELETE</param-value>
		</init-param>
		<init-param>
			<param-name>cors.supportedHeaders</param-name>
			<param-value>Accept, Origin, X-Requested-With, Content-Type, Last-Modified</param-value>
		</init-param>
		<init-param>
			<param-name>cors.exposedHeaders</param-name>
			<param-value>Set-Cookie</param-value>
		</init-param>
		<init-param>
			<param-name>cors.supportsCredentials</param-name>
			<param-value>true</param-value>
		</init-param>
	</filter>
	<filter-mapping>
		<filter-name>CORS</filter-name>
		<url-pattern>/*</url-pattern>
	</filter-mapping>  
	

加上之后重启程序,别的机器访问,可以了 ,里边可以看接口列表并且可以接口测试,爽呆了:


但是要注意,这里的配置是允许所有的ip访问,这样会相应的出现安全问题,大家请参考这篇文章:http://www.freebuf.com/articles/web/18493.html,写的很好,小编对网络安全还不是很了解,但是起码,最简单的swagger可以用了,希望写的有问题的地方大家积极的指正,谢谢,共勉。

版权声明:本文为博主原创文章,未经博主允许不得转载。

springmvc集成swagger实现接口文档自动化生成

一直苦于文档整理工作,因为这是一个很无聊的工作,偶然在网上看到了swagger这东西,感觉不错,于是动手集成了一下,眼前一亮           Swagger 是一个规范和完整的框架,用于生成...
  • q1512451239
  • q1512451239
  • 2016年11月29日 10:16
  • 1298

springmvc集成swagger实现接口文档自动化生成

一直苦于文档整理工作,因为这是一个很无聊的工作,偶然在网上看到了swagger这东西,感觉不错,于是动手集成了一下,眼前一亮           Swagger 是一个规范和完整的框架,用于生成、描述...
  • liufei198613
  • liufei198613
  • 2016年07月01日 16:17
  • 7018

springmvc集成Swagger自动生成api文档

springmvc集成Swagger自动生成api文档准备工作下载swaggerUI: https://github.com/swagger-api/swagger-ui maven项目中,添加pom...
  • duanjiajia
  • duanjiajia
  • 2017年01月11日 10:56
  • 1831

Spring MVC学习总结(9)——Spring MVC整合swagger自动生成api接口文档

Swagger 号称:世界最流行的API框架,官网:http://swagger.io/,Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总...
  • u012562943
  • u012562943
  • 2016年11月02日 09:45
  • 1559

Spring-Boot + Swagger2 自动生成API接口文档

spring-boot作为当前最为流行的Java web开发脚手架,相信越来越多的开发者会使用其来构建企业级的RESTFul API接口。这些接口不但会服务于传统的web端(b/s),也会服务于移动端...
  • amon1991
  • amon1991
  • 2017年08月06日 15:51
  • 1085

Spring Boot学习笔记 - 整合Swagger2自动生成RESTful API文档

在App后端开发中经常需要对移动客户端(Android、iOS)提供RESTful API接口,在后期版本快速迭代的过程中,修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,...
  • FX_SKY
  • FX_SKY
  • 2017年01月04日 19:28
  • 5321

Spring Boot进阶1 - 整合Swagger2自动生成RESTful API文档

本文将介绍RESTful API可视化调试工具Swagger2,它可以轻松的整合到spring生态链中,并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的...
  • qq_15969757
  • qq_15969757
  • 2017年04月13日 18:00
  • 345

spring boot rest接口自动生成文档(包含swagger)

spring boot rest接口自动生成文档(包含swagger)      写接口免不了写接口文档,但是当文档与代码分开独立演进的时候,会发生很多不同步的问题。         接口描述与代...
  • doctor_who2004
  • doctor_who2004
  • 2017年06月22日 19:28
  • 996

SpringMVC中使用swagger为api接口生成文档

1.添加swagger的maven依赖 com.fasterxml.jackson.core jackson-databind 2.6.0 com.mangofactory...
  • zhanjixun
  • zhanjixun
  • 2017年01月17日 12:11
  • 1437

使用apidoc自动生成rest风格api接口文档

1 先下载安装nodejs,下载地址: 点击打开链接 2 安装apidoc,命令行执行: npm install apidoc -g 安装完成后执行: apidoc --help 检验一下是...
  • znsqingfeng
  • znsqingfeng
  • 2016年05月24日 17:24
  • 1529
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:swagger和springmvc结合自动生成api接口文档
举报原因:
原因补充:

(最多只允许输入30个字)