简单好用的Restful 风格的 Web 服务框架-----Swagger

前言

---

提示：以下是本篇文章正文内容，下面案例可供参考

一、swagger是什么？

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。简单的说，Swagger是在线动态生成的接口API文档，有了它，再也不用因为后台接口的频繁改动而心力交瘁的去修改手动编写的DOC接口文档。

二、优势

1、根据定义的接口动态生成API,Swagger是在线动态生成的接口API文档，有了它，再也不用因为后台接口的频繁改动而心力交瘁的去修改手动编写的DOC接口文档。

2.、不仅动态生成API,Swagger 生成的文档还支持在线测。

三、Springboot项目集成Swagger

1.方式一

POM文件中引入启动类，代码如下（示例）：

		<dependency>
			<groupId>com.spring4all</groupId>
			<artifactId>swagger-spring-boot-starter</artifactId>
			<version>1.8.0.RELEASE</version>
		</dependency>

yum配置文件，代码如下（示例）：

		swagger:
		   base-package: hk.wisdom.controller
		   authorization:
		     key-name: Authorization

最后在启动类加入@EnableSwagger2Doc注解，配置启动项目时启动，代码如下（示例）：

@SpringBootApplication
@EnableSwagger2Doc
@Api("wisdom学习平台")
@MapperScan(basePackages= {"hk.wisdom.dao"})
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class ServerLmsApplication {
	public static void main(String[] args) {
		SpringApplication.run(ServerLmsApplication.class, args);
	}

访问地址：http://localhost:8088/swagger-ui.html#/ 如下图（示例）：

注解使用统一在方式二中说明

方式二

POM文件中引入启动类，代码如下（示例）：

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.8.0</version>
		</dependency>
		
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.8.0</version>
		</dependency>
		
		<!--界面样式修改，界面将修改成传统的管理系统界面，可根据个人喜好决定是否修改-->
		<dependency>
		   <groupId>com.github.caspar-chen</groupId>
		   <artifactId>swagger-ui-layer</artifactId>
		   <version>1.1.3</version>
		</dependency>

yum配置文件，代码如下（示例）：

		swagger:
		   enabled: true

新增配置文件SwaggerConfig，配置扫描的路径和页面显示的信息，这种写法的好处是自己可以很方便修改页面显示的标题版本等内容，缺点是配置相较于方式一，麻烦了一点。代码如下（示例）：

package hk.wisdom.config;
import org.springframework.beans.factory.annotation.Value;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@Configuration
public class SwaggerConfig {
	// 是否开启swagger，正式环境一般是需要关闭的，可根据springboot的多环境配置进行设置，配置文件中 enabled: true
	@Value(value = "${swagger.enabled}")
	Boolean swaggerEnabled;

	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
				// 是否开启
				.enable(swaggerEnabled).select()
				// 扫描的路径包，可自己定义
				.apis(RequestHandlerSelectors.basePackage("hk.wisdom.controller"))
				// 指定路径处理PathSelectors.any()代表所有的路径
				.paths(PathSelectors.any()).build().pathMapping("/");
	}

	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("智能数据监控分析平台在线接口API").description("springboot | swagger")
				// 作者信息
				.contact(new Contact("zyf", "https://xxxxxxxxxx/", "1798737296@qq.com"))
				.version("1.0.0").build();
	}
}

---

四、常用注解使用

controller注解使用，代码如下（示例）：

	@Controller
@RequestMapping("/aging")
public class AgingDataController {
	@Autowired
	AgingDataService agingDataService;

	@ApiOperation(value = "数据写入接口")  //接口说明，还可以使用 notes ="xxxxxxxx",对接口进行详细描述，可根据自己实际需要增加
	@ResponseBody
	@PostMapping("/insertAgingData")  //不指定哪种方式，页面将会将所有请求方式都显示，本例采用post
	public JSONObject insertAgingData(@RequestBody AgingData agingData) {
		return agingDataService.insertAgingData(agingData);
	}
}

对于实体类使用@ApiModel，@ApiModelProperty注解来说明参数特性或是否需要必填，像ID是自增项，完全不需要我们传递参数，显示在页面又不美观，就可以隐藏起来，页面参数就不会显示出来。代码如下（示例）：

@ApiModel
public class AgingData {
	@ApiModelProperty(hidden = true)
	private Integer id;
	@ApiModelProperty(name = "lampId", value = "灯的编号", required = true)  //name 参数名；value 参数描述  required 是否必传
	private String lampId;
	}

测试页面，本文实体类AgingData 中变量只举了两个例子，ID不会显示，带红色* 的则是定义的必填项 如下（示例）：

五、总结

其实归根到底，使用Swagger，可以极大的简化我们编写接口文档的复杂程度，更不会因为接口频繁的变动，而去频繁的更改接口文档API,合理的使用Swagger在线接口，可以很好的帮助我们处理接口问题。另外，可以结合postman工具一起使用，postman相较于swagger还支持文件上传测试,多种格式参数、授权验证等功能，二者结合使用非常不错。