为什么要用Swagger2?
在开发过程中为了减少平时与其他团队的频繁沟通成本,我们通常会创建一份RESTful API文档来记录所有接口的细节,但是这样做的话会有一些问题:
- 一个大型的项目往往会有超级多的接口,由于接口数量众多,而且细节比较复杂,高质量的把这份文档编写完成,本身就是一个超级困难的事情,下层编写文档的程序员们怨声不绝于耳。
- 随着时间的推移,会不断修改接口的实现,这个时候也就必须要修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象。
为了解决这些问题,给大家介绍一下RESTful API文档的重磅好伙伴Swagger2,它可以轻轻松松整合进Spring Boot中,并与Spring MVC程序配合组织出强大的RESTful API文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。
下面开始进行整合,首先在pom.xml中加入Swagger2的依赖:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
接下来编写Swagger配置类,加上@Configuration注解,这个类的东西其实只需要了解具体能配置哪些东西就行了,毕竟这个类配置一次以后就不再改了。需要注意的是里面是配置了Controller包的路径,不然扫描不到接口。
package com.test.swagger.demo;
import org.springframework.context.annotation.Bean;
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;
/**
* @Auther: 史敦凯
* @Date: 2019/4/27 14:49
* @Description: Swagger2配置类
*/
@Configuration
public class SwaggerConfig {
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.test.swagger.demo.controller"))
.paths(PathSelectors.any())
.build();
}
//用来创建该Api的基本信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger2构建api文档")
.description("说明文字XXX")
.termsOfServiceUrl("https://www.csdn.net/")
.version("1.0")
.build();
}
}
}
在Spring Boot的启动类上加入注解@EnableSwagger2,表示开启Swagger。
@SpringBootApplication
@EnableSwagger2
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
下一步是编写Restful接口,在这之前我们先建立一个实体类:
public class User implements Serializable{
private int id;
private String name;
private int age;
//此处省略 Getter和 Setter方法
}
package com.test.swagger.demo.controller;
import com.test.swagger.demo.bean.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
import java.util.HashMap;
/**
* @Auther: 史敦凯
* @Date: 2019/4/27 15:14
* @Description:
*/
@RestController
public class UserController {
//创建一个Map用来存储User对象,模拟数据库操作
static HashMap<Integer, User> userHashMap = new HashMap<>();
//往Map里塞入一些数据
static {
userHashMap.put(1, new User(1, "蔡徐坤", 26));
userHashMap.put(2, new User(2, "吴亦凡", 24));
userHashMap.put(3, new User(3, "孙悟空", 344));
userHashMap.put(4, new User(4, "二师兄", 119));
}
@ApiOperation(value = "获取用户信息", notes = "根据id获取用户详细信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
@GetMapping("user/{id}")
public User getUserById(@PathVariable Integer id) {
User user = userHashMap.get(id);//查询数据
//返回数据
return user;
}
}
启动项目,访问 http://localhost:8080/swagger-ui.html
看到这个页面说明成功进入了Swagger2,这里会显示我们添加的描述文字,然后我们输入一个1进行测试一下:
很明显这个接口测试成功了,已经显示出来了查询结果:
项目结构如下:
最后说一下Swagger2的注解,Swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等:
- @Api:修饰整个类,描述Controller的作用
- @ApiOperation:描述一个类的一个方法,或者说一个接口
- @ApiParam:单个参数描述
- @ApiModel:用对象来接收参数
- @ApiProperty:用对象接收参数时,描述对象的一个字段
- @ApiResponse:HTTP响应其中1个描述
- @ApiResponses:HTTP响应整体描述
- @ApiIgnore:使用该注解忽略这个API
- @ApiError :发生错误返回的信息
- @ApiImplicitParam:一个请求参数
- @ApiImplicitParams:多个请求参数