RESTful API的灵魂伴侣——Swagger

开篇总是要写一些概括性的东西！

Swagger 是一个RESTful接口的文档的实时生成与测试工具。没接触过类似工具的你可能对这句话没什么概念，不要急，我来慢慢解释。

使用REST的原因之一就是方便前后端分离开发，后端开发者写后端的逻辑，前端开发者写前端的逻辑，然后大家约定好一个API的风格，使用HTTP的get、post、put、delete来对应资源的CURD。避免了这种情况的发生：前端开发者拿着后端提供的厚厚的API文档边查阅边愤愤地开发，每个业务逻辑对应一个接口规范，混乱不堪。然后某一天后端改了逻辑，删掉了几个接口又增加了几个接口，前端又要大范围地改代码，然后前后端就打起来了。

为了避免打架，规范了API的设计，使用了较为轻便的RESTful风格。而Swagger起到一个锦上添花的作用，它使得前后端的协同变得更加效率。后端开发者在定义好接口后，Swagger会自动生成并更新文档，文档中会详细记录接口的使用方法，需要传入哪些参数，又会返回什么样的结果，即节约了写文档的时间，又提高了文档的同步速度，提高了开发效率。另外Swagger不止这些功能，它还有一个强大的功能，就是在文档中直接对接口进行测试，我们可以使用Swagger模拟用户的真实操作，向后台发一个请求来验证接口是否满足需求。说了这么多，可能你还是不太明白，那我直接贴张图片吧，下图就是Swagger生成的文档：

算了，不截图了，直接给个链接吧：http://petstore.swagger.io/?_ga=2.151670393.1145939008.1514200525-1067691787.1514200525

这是官方提供一个demo文档，可以简单操作一下，聪明的你应该豁然开朗了吧！

好了，Swagger介绍完了，相信大家已经认识他了吧。下面我将介绍如何在spring mvc项目中嵌入Swagger：

本文使用 springfox-swagger实现Swagger的集成。很简单，仅仅几步就可搞定！

步骤↓：

引入jar包，此处笔者使用maven，直接引入依赖：

		<!-- swagger RestfulAPI 文档工具 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>${springfox.version}</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>${springfox.version}</version>
		</dependency>

此处使用的版本是springfox.version=2.6.1

重写一下Swagger的配置类并声明成bean：

package com.ds.core.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

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

@EnableWebMvc
@EnableSwagger2
@ComponentScan("com.ds.literary.controller")//配置Swagger要扫描的包
@Configuration
public class SwaggerConfig extends WebMvcConfigurationSupport {

	@Bean
	public Docket docket() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo())
				.groupName("Du")
				.select()
//				.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
//				.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
				.paths(PathSelectors.any())
				.build();
	}

//	@Bean
//	public Docket xxx() {
//		return new Docket(DocumentationType.SWAGGER_2)
//				.apiInfo(apiInfo())
//				.groupName("xxx")
//				.select()
//				.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
//				.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//				.paths(PathSelectors.ant("/xxx/**"))
//				.build();
//	}

	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("Ds")
				.contact(new Contact("Du", "", "[email protected]"))
				.version("0.0.1")
				.build();
	}
}

在写controller的时候加入一些annotation就好了：

@RestController
@RequestMapping("/blog")
@Api(value = "管理用户发表的博客，文章，日志接口", description = "管理用户发表的博客，文章，日志接口")
public class BlogController extends BaseController<Blog>{
	public String getService() {
		return "blogService";
	}

	@PutMapping
	@ApiOperation(value = "修改用户发表的博客，文章，日志", produces = MediaType.APPLICATION_JSON_VALUE)
	public Object update(HttpServletRequest request, @RequestBody Blog param) {
                ModelMap modelMap = new ModelMap();
                long authorId=getCurrUser();
                param.setAuthorId(authorId);
		return super.update(modelMap, param);
	}

	@DeleteMapping
	@ApiOperation(value = "删除用户发表的博客，文章，日志", produces = MediaType.APPLICATION_JSON_VALUE)
	public Object delete(HttpServletRequest request, @RequestBody Blog param) {
                ModelMap modelMap = new ModelMap();
		return super.delete(modelMap, param);
	}
}

在spring中配置一个资源重定向：

<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />

启动项目，打开默认文档界面http://localhost:8080/ds-sys-web/swagger-ui.html，这个路径根据你的实际情况修改。如果你觉得这个界面丑，是可以自己定制的，具体方法本篇就不介绍了。

下面是成功后的截图：

搞定！

RESTful API的灵魂伴侣——Swagger

猜你喜欢