摘要:在项目开发中,往往期望做到前后端分离,也就是后端开发人员往往需要输出大量的服务接口,接口的提供方无论是是 Java还是PHP等语言,往往会要花费一定的精力去写接口文档,比如A接口的地址、需要传递参数情况、返回值的JSON数据格式以及每一个字段说明、当然还要考虑HTTP请求头、请求内容等信息。随着项目的进度快速高速的迭代,后端输出的接口往往会面临修改、修复等问题,那也意味着接口文档也要进行相应的调整。接口文档的维护度以及可读性就大大下降。既然接口文档需要花费精力去维护,还要适当的进行面对面交流沟通,我们何不想一个办法,第一:可以不用写接口文档;第二:前端与后端沟通接口问题的时候,后端是否可以提供一个URL,在这个URL中罗列出所有可以调用的服务接口,并在每个服务接口中罗列出参数的说明,返回值的说明,第三:后端接口如果能模拟调用就所有问题都解决了。本文我们重点讲解一下Sringboot中集成 Swagger2 框架。
在项目的 pom.xml文件中增加如下的依赖。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
首先,我们需要建立一个启动类,代码如下:
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
然后在上述类的同级目录中新建 swagger2的配置类如下所示:
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.shareniu.web"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("跟着分享牛学习Springboot源码分析系列课程")
.description("更多Spring Boot相关文章请关注分享牛的博客")
.termsOfServiceUrl("http://www.shareniu.com/")
.contact("牛牛")
.license("Copyright 2017-2018 分享牛")
.version("1.0")
.build();
}
}
@Configuration制定了spring要加载这个类,@EnableSwagger2注解要开启Swagger功能。
上述中的 ApiInfo最终都会展现在前端,我们使用了扫描包的方式配置配置,也就是RequestHandlerSelectors.basePackage。在这个包以及子包中的控制器最终都是生成API文档。(除了被@ApiIgnore注解 指定的请求)。
上述的类声明之后,我们其实就可以直接调用了,但是为了增加文档的可读性,我们还是需要在接口中增加一些说明,我们先写一个控制器如下所示:
@RestController
@RequestMapping(value="/users")
public class UserController {
static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());
static {
User user = new User();
user.setAge(18);
user.setId(1L);
user.setName("aa");
users.put(1L, user);
}
@ApiOperation(value="获取所有用户列表", notes="")
@RequestMapping(value={""}, method=RequestMethod.GET)
public List<User> getUserList() {
List<User> r = new ArrayList<User>(users.values());
return r;
}
@ApiOperation(value="创建新的用户", notes="根据User对象创建用户")
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
@RequestMapping(value="", method=RequestMethod.POST)
public String postUser(@RequestBody User user) {
users.put(user.getId(), user);
return "success";
}
@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@RequestMapping(value="/{id}", method=RequestMethod.GET)
public User getUser(@PathVariable Long id) {
return users.get(id);
}
@ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
})
@RequestMapping(value="/{id}", method=RequestMethod.PUT)
public String putUser(@PathVariable Long id, @RequestBody User user) {
User u = users.get(id);
u.setName(user.getName());
u.setAge(user.getAge());
users.put(id, u);
return "success";
}
@ApiOperation(value="删除已存在的用户", notes="根据url的id来指定删除对象")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@RequestMapping(value="/{id}", method=RequestMethod.DELETE)
public String deleteUser(@PathVariable Long id) {
users.remove(id);
return "success";
}
}
@ApiOperation:用来描述该接口的作用。可以通过该注解说明接口的职责、返回头信息、方法的请求方式("GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH")、协议( http, https, ws, wss )、 http状态码。
@ApiImplicitParam:用来给参数增加说明。可以设置参数的名称、是否是必填项、参数的描述信息、是否只读等。
上述代码提交之后,启动 springboot,访问http://127.0.0.1:8080/swagger-ui.html,如下图所示:
上图分为两个部分,上部分是通过 Swagger2类配置出来的,下半部分是UserController类中的接口文档。
这里我们以 /user为例进行说明:
点击 /user如下图所示:
上图黄色的地方表示,该接口返回的样例数据。也就是 User的数据结构。Response Content Type:接口返回的头信息。点击Try it out。如下所示:
该接口返回的 baody、code码、响应头已经成功返回了。