2019独角兽企业重金招聘Python工程师标准>>> 
SpringBoot入门——使用Swagger2构建Restful API文档
自己写程序测试时写的，不喜勿喷，可能有错，欢迎纠正
一、背景
由于Spring Boot能够快速开发、便捷部署等特性，相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因，这些终端会共用很多底层业务逻辑，因此我们会抽象出这样一层来同时服务于多个移动端或者Web前端。
这样一来，我们的RESTful API就有可能要面对多个开发人员或多个开发团队：IOS开发、Android开发或是Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本，传统做法我们会创建一份RESTful API文档来记录所有接口细节，然而这样的做法有以下几个问题：
- 由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就是件非常吃力的事，下游的抱怨声不绝于耳。
- 随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致不一致现象。
为了解决上面这样的问题，本文将介绍RESTful API的重磅好伙伴Swagger2，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。
二、Swagger简介
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
三、SpringBoot中应用Swagger2
(1)、新建Maven项目
项目名称:springboot
(2)、在pom中引入Springboot项目需要的包
新建Maven项目，往其中pom.xml中引入Springboot需要的包
4.0.0
com.springboot
spring-boot2
0.0.1-SNAPSHOT
jar
springboot
http://maven.apache.org
org.springframework.boot
spring-boot-starter-parent
1.5.4.RELEASE
UTF-8
1.8
org.springframework.boot
spring-boot-starter-web
org.springframework.boot
spring-boot-devtools
true
true
org.springframework.boot
spring-boot-maven-plugin
true
(3)、在pom中引入Swagger需要的包
io.springfox
springfox-swagger2
2.7.0
io.springfox
springfox-swagger-ui
2.7.0
(4)、创建Swagger2配置类
包名：com.springboot.config
类名：SwaggerConfig
package com.springboot.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;
@Configuration
// 启用swagger
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(this.apiInfo())
.groupName("XX组")
.useDefaultResponseMessages(false)
.enableUrlTemplating(false)
.select()
.apis(RequestHandlerSelectors.basePackage("com.springboot.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot Swagger2 By Test")
.description("XX项目API")
.termsOfServiceUrl("127.0.0.1:8080/test/")
.version("0.0.1")
.build();
}
}
参数说明：
----------------------------------------------------------------------------------
- @Configuration：声明此类为配置类,让Spring加载
- @EnableSwagger2：启用Swagger2
----------------------------------------------------------------------------------
- apiInfo()：创建该Api的基本信息
- groupName()：设置组名
- useDefaultResponseMessages()：使用默认的响应信息，一般设置false
- enableUrlTemplating(false)：使模板的URL
----------------------------------------------------------------------------------
- apis()：扫描哪些包
- PathSelectors.any()：任何满足条件的路径
----------------------------------------------------------------------------------
(5)、创建Controller类
包名：com.springboot.controller;
类名：HelloController
package com.springboot.controller;
import static org.springframework.util.MimeTypeUtils.APPLICATION_JSON_VALUE;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import com.springboot.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
@RestController
@RequestMapping("/test")
@Api(tags="与检查单有关的接口")
public class HelloController {
@ApiOperation(value = "获得hello字符串JSON", response = String.class, produces = APPLICATION_JSON_VALUE
,notes = "根据User对象创建用户")
@RequestMapping(value = { "/hello" }, method = RequestMethod.GET)
public String hello() {
return "hello";
}
@ApiOperation(value = "修改用户", response = String.class, produces = APPLICATION_JSON_VALUE
,notes = "根据id修改用户")
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
@RequestMapping(value = { "/modifyUser" }, method = RequestMethod.POST)
public User modifyUser(@RequestBody User user) {
user.setName("张三");
user.setAge(20);
return user;
}
}参数说明：
----------------------------------------------------------------------------------
- @Api：对Controller项的标题描述信息设置
- @ApiOperation：对接口信息进行描述
- name：参数名
- value：参数描述信息
- required：是否可以发送请求信息进行测试
- dataType：数据类型
- @ApiImplicitParam：对接口的方法的参数进行描述
- value：操作项名字设置
- response：返回类型设置
- response：返回数据格式
- notes：此项的描述信息
----------------------------------------------------------------------------------
三、管理接口的地址
http://localhost:8080/swagger-ui.html