永远不要跟别人比幸运,我从来没想过我比别人幸运,我也许比他们更有毅力,在最困难的时候,他们熬不住了,我可以多熬一秒钟、两秒钟,甚至更久。

Spring Boot 整合 Swagger2

Java 新民 246℃ 已收录 1评论

1、什么是Swagger
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
Swagger的目标是为REST APIs 定义一个标准的,与语言无关的接口,使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义,消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口,Swagger去掉了调用服务时的很多猜测。

2、为什么要使用Swagger

想想我们之前在项目中的接口,通常都要给每个接口写对应的接口文档,如果项目中的接口都是内部使用并且开发团队都在一起,也许可以省掉写接口文档,开发一个新的接口直接口头表述,后面自己去看这些接口都不知道是干什么用,更别说接口给外部团队使用了。之前编写接口文档可能都是用Word文档写或者用javadoc注释生成文档。两种都比较麻烦,手写耗时耗力,生成文档每次都要编译一遍。使用Swagger则可以快速的生成文档。

3、使用Swagger的好处

前后端分离开发
API文档非常明确
测试的时候不需要再使用URL输入浏览器的方式来访问Controller
传统的输入URL的测试方式对于post请求的传参比较麻烦(当然,可以使用postman这样的浏览器插件)
Swagger与SpringBoot的集成简单

4、开始整合
(1)添加依赖Jar包

    <!-- swagger2 -->
		<dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger2</artifactId>
		    <version>2.9.2</version>
		</dependency>
		
		<!-- swagger 2 ui -->
		<dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger-ui</artifactId>
		    <version>2.9.2</version>
		</dependency>	

(2)编写配置代码

    package com.snowruin.common.config;

	import org.springframework.context.annotation.Bean;
	import org.springframework.context.annotation.Configuration;

	import springfox.documentation.builders.ApiInfoBuilder;
	import springfox.documentation.builders.PathSelectors;
	import springfox.documentation.builders.RequestHandlerSelectors;
	import springfox.documentation.service.ApiInfo;
	import springfox.documentation.spi.DocumentationType;
	import springfox.documentation.spring.web.plugins.Docket;
	import springfox.documentation.swagger2.annotations.EnableSwagger2;

	/**
	 * swagger 文档配置
	 * 
	 * @author zxm
	 *
	 */
	@Configuration
	@EnableSwagger2
	public class SwaggerConfig {

		@Bean
		public Docket createRestApi() {
			return new Docket(DocumentationType.SWAGGER_2)
					.apiInfo(apiInfo())
					.select()
					.apis(RequestHandlerSelectors.basePackage("com.snowruin.controller"))
					.paths(PathSelectors.any()).build();
		}
		
		
		
		private ApiInfo apiInfo() {
			return new ApiInfoBuilder()
					.title("spring boot 文档")
					.description("简单优雅的rest风格")
					.termsOfServiceUrl("http://www.snowruin.com")
					.version("2.0")
					.build();
		}
	}

(3)编写访问路径:

    /**
	 * zhaoxinmin
	 */
	@Configuration
	public class MvcConfig extends WebMvcConfigurationSupport {


		/**
		 * 配置静态访问资源
		 * @param registry
		 */
		@Override
		public void addResourceHandlers(ResourceHandlerRegistry registry) {
			//自定义项目内目录
			//registry.addResourceHandler("/my/**").addResourceLocations("classpath:/my/");
			//指向外部目录
			registry.addResourceHandler("/my/**").addResourceLocations("file:E:/my/");
			registry.addResourceHandler("swagger-ui.html")
					.addResourceLocations("classpath:/META-INF/resources/");
			registry.addResourceHandler("/webjars/**")
					.addResourceLocations("classpath:/META-INF/resources/webjars/");
			super.addResourceHandlers(registry);
		}
    }

(4)编写接口

    @RestController
	@RequestMapping("/api")
	@Api(value="主要接口",description="主要接口")
	public class MainController {
		/**
		 * 登录
		 * @param snCdoe
		 * @return
		 */
		@ApiOperation(value="登录")
		@ApiImplicitParam(name="snCode",value="pad的设备码")
		@PostMapping("/login")
		public ResponseEntity login(@RequestParam("snCode")String snCdoe){
			Pad pad = padService.selectPadBySn(snCdoe);
			if(pad == null) {
				return new ResponseEntity(new Result("500", "未查询到相关pad信息"),HttpStatus.OK);
			}
			
			Customer customer = this.customerService.selectCustomerByPK(pad.getCustomerId());
			if(customer == null) {
				return new ResponseEntity(new Result("500", "未查询到相关用户信息"),HttpStatus.OK);
			}
			
			List armets = this.armetService.selectArmetListByPadId(pad.getId());
			return new ResponseEntity(new Result("200", "查询成功",new HashMap<String,Object>(2) {/**
				 * 
				 */
				private static final long serialVersionUID = 1L;

			{
				put("customerName", customer.getName());
				put("armets",armets);
				put("armetCount", pad.getArmetCount());  // 可控制的头显数量
			}}) , HttpStatus.OK);
		}
	}

(5)打开浏览器输入访问地址: http://localhost:8090/swagger-ui.html ,表过如下

至此,Spring Boot 和 Swagger2 的整合已经完成,下面来介绍下,Swagger2 的常用注解有哪些:
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数

本站文章如未注明,均为原创丨本网站采用BY-NC-SA协议进行授权,转载请注明转自:http://www.snowruin.com/?p=1753
喜欢 (0)or分享 (0)
发表我的评论
取消评论
表情 代码 贴图 加粗 链接 私信 删除线 签到

Hi,请填写昵称和邮箱!

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址
(1)条精彩评论。
  1. 呵呵。学习了。感触良多!
    罗拉2018-09-30 08:04 回复| Google Chrome 14.0.802.30| Windows 7