目前，大多数系统都采用前后端分离。一般都是前后端先行沟通设计接口文档，前后端同时进行开发工作。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。
2. 快速入门 Swagger在 springboot maven项目pom.xml 文件中，引入相关依赖。
org.springframework.boot spring-boot-starter-web io.springfox springfox-swagger2 2.9.2 io.springfox springfox-swagger-ui 2.9.2
创建 SwaggerConfiguration 配置类，用于配置 Swagger 。代码如下：
package com.gl.lab01.swagger.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2 // 标记项目启用 Swagger API 接口文档
public class SwaggerConfiguration {
@Bean
public Docket createRestApi() {
// 创建 Docket 对象
return new Docket(DocumentationType.SWAGGER_2) // 文档类型，使用 Swagger2
.apiInfo(this.apiInfo()) // 设置 API 信息
// 扫描 Controller 包路径，获得 API 接口
.select()
// 项目的controller包路径
.apis(RequestHandlerSelectors.basePackage("com.gl.lab01.swagger.controller"))
.paths(PathSelectors.any())
// 构建出 Docket 对象
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("测试接口文档示例")
.description("描述")
.version("1.0.0") // 版本号
.contact(new Contact("name111", "http://www.baidu.cn", "666666.qq@com")) // 联系人
.build();
}
}
Application.java 类：
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
Controller：
package com.gl.lab01.swagger.controller;
import com.gl.lab01.swagger.dto.UserAddDTO;
import com.gl.lab01.swagger.dto.UserUpdateDTO;
import com.gl.lab01.swagger.vo.UserVO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;
import java.util.UUID;
@RestController
@RequestMapping("/users")
@Api(tags = "用户 API 接口")
public class UserController {
@GetMapping("/list")
@ApiOperation(value = "查询用户列表", notes = "所以返回用户全列表")
public List list() {
// 查询列表
List result = new ArrayList<>();
result.add(new UserVO().setId(1).setUsername("helloWord"));
result.add(new UserVO().setId(2).setUsername("helloWord1"));
result.add(new UserVO().setId(3).setUsername("helloWord2"));
// 返回列表
return result;
}
@GetMapping("/get")
@ApiOperation("获得指定用户编号的用户")
@ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "666")
public UserVO get(@RequestParam("id") Integer id) {
// 查询并返回用户
return new UserVO().setId(id).setUsername(UUID.randomUUID().toString());
}
@PostMapping("add")
@ApiOperation("添加用户")
public Integer add(UserAddDTO addDTO) {
// 插入用户记录，返回编号
Integer returnId = UUID.randomUUID().hashCode();
// 返回用户编号
return returnId;
}
@PostMapping("/update")
@ApiOperation("更新指定用户编号的用户")
public Boolean update(UserUpdateDTO updateDTO) {
// 更新用户记录
Boolean success = true;
// 返回更新是否成功
return success;
}
@PostMapping("/delete")
@ApiOperation(value = "删除指定用户编号的用户")
@ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024")
public Boolean delete(@RequestParam("id") Integer id) {
// 删除用户记录
Boolean success = false;
// 返回是否更新成功
return success;
}
}
执行 Application 启动项目。然后浏览器访问 http://127.0.0.1:8080/swagger-ui.html 地址，就可以看到 Swagger 生成的 API 接口文档。如下图所示：
