swagger的简介及使用方法

Swagger 是一个用于描述、生成、文档化和测试 RESTful API 的开源工具集。它可以自动生成 API 文档，帮助开发者理解和使用 API。Swagger 由 Swagger.io 提供，并已经发展成了一套广泛应用于 API 设计和文档的标准。

Swagger 项目的历史可以追溯到 2010 年，它最初由 Tony Tam 创建。当时，API 开发者通常需要花费大量时间手动编写和维护文档，并且手动维护文档容易与实际 API 的实现不一致，导致文档和实际接口的差异。Swagger 的设计目标就是通过自动生成文档，减少这些手动工作，提高开发效率。

发展历程

2011年：
- Swagger 在 GitHub 上开源发布，迅速吸引了开发者的关注。它提供了一个简单的注解系统，开发者通过在代码中添加注解即可自动生成 API 文档。Swagger 可以帮助开发者和团队更好地理解和使用 API。
2015年：
- Swagger 被纳入 OpenAPI Initiative (OAI)，一个由多个技术公司和开源社区组成的组织，旨在制定开放的 API 规范。OpenAPI 规范（OAS，OpenAPI Specification）取代了原有的 Swagger 规范，成为更加标准化的 API 描述格式。
- Swagger 工具集的名字也被保持了下来，仍然用于描述和生成 API 文档，而 OpenAPI 则成为技术规范。
2016年：
- Swagger 发布了 Swagger 2.0，并继续进行更新与完善。Swagger 2.0 是 Swagger 生态系统的基础，至今仍被广泛使用。
2017年以后：
- OpenAPI 3.0 规范发布，它包含了对 Swagger 2.0 的改进和扩展，提供了更强大的功能。Swagger 的工具链也开始支持 OpenAPI 3.0 规范，并向兼容性过渡。

Swagger 的主要组件

Swagger 的工具集包括多个组成部分，使得开发者可以更好地设计和管理 API：

Swagger Editor：
- 一个基于 Web 的编辑器，可以帮助开发者编写和编辑 OpenAPI 规范文件（通常为 swagger.yaml 或 swagger.json 文件）。它支持实时预览和验证 API 规范。
Swagger UI：
- Swagger UI 是一个基于浏览器的界面，提供交互式文档界面，允许开发者和用户查看 API 文档，并直接在文档界面上测试 API 的各个端点。
Swagger Codegen：
- Swagger Codegen 允许开发者从 OpenAPI 规范中自动生成客户端 SDK、服务器端代码和 API 文档。这些代码生成器支持多种编程语言和框架。
Swagger Hub：
- Swagger Hub 是一个商业化平台，用于协作设计、构建和管理 API 文档。它提供了基于云的 API 管理、版本控制和协作功能，适用于企业级应用。

Swagger 的优点

自动化文档生成：通过注解，Swagger 可以自动生成 API 的文档，避免手动编写文档，减少出错概率。
易于使用：开发者可以通过简单的注解和配置文件来定义 API，Swagger UI 提供了交互式的界面，方便开发者和用户查看和测试 API。
开源和广泛支持：Swagger 是开源的，得到了广泛的社区支持，并且能够与许多开发框架（如 Spring、Node.js、Java、Python 等）兼容。

Swagger 的使用

1. `@Api`

作用：用于标记一个类是一个 Swagger 资源（通常是一个 Controller 类）。
常见用法：

@Api(tags = "用户管理", description = "管理用户的 API")
public class UserController {// 控制器代码
}

2. `@ApiOperation`

作用：描述单个 API 操作（通常是一个方法），提供接口的详细信息，如功能说明、HTTP 方法、响应类型等。

常见用法：

@ApiOperation(value = "获取用户列表", notes = "获取所有用户的列表", response = User.class)
@GetMapping("/users")
public List<User> getUsers() {// 代码
}

3. `@ApiParam`

作用：用于描述方法参数的详细信息（例如：是否必需、默认值等）。

常见用法：

@ApiOperation("获取指定用户")
@GetMapping("/user/{id}")
public User getUser(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) {// 代码
}

4. `@ApiResponse`

作用：描述 API 操作的响应信息，例如状态码和响应类型。

常见用法：

@ApiOperation(value = "删除用户", notes = "删除指定用户")
@ApiResponses({@ApiResponse(code = 200, message = "删除成功"),@ApiResponse(code = 404, message = "用户未找到")
})
@DeleteMapping("/user/{id}")
public ResponseEntity<Void> deleteUser(@PathVariable Long id) {// 代码
}

5. `@ApiModel`

作用：用于定义 API 中的复杂对象模型（即请求体或响应体），例如对象参数或返回的复杂数据类型
常见用法：

@ApiModel(description = "用户对象")
public class User {@ApiModelProperty(value = "用户ID", required = true)private Long id;@ApiModelProperty(value = "用户姓名", example = "张三")private String name;
}

6. `@ApiModelProperty`

作用：用于为模型属性提供详细描述，包括字段说明、是否必填、默认值等。
常见用法：

public class User {@ApiModelProperty(value = "用户ID", required = true)private Long id;@ApiModelProperty(value = "用户姓名", example = "张三")private String name;
}

7. `@PathParam`, `@QueryParam`, `@HeaderParam`, `@FormParam`

作用：用于绑定 HTTP 请求的路径、查询参数、请求头和表单参数。它们分别对应不同类型的参数提取。
常见用法：

@GetMapping("/user")
public User getUser(@QueryParam("id") Long id) {// 代码
}

8. `@RequestBody`

作用：用于标注方法参数接收请求体的数据，通常用来处理 JSON 或 XML 格式的请求。
常见用法：

@PostMapping("/user")
public User createUser(@RequestBody User user) {// 代码
}

9. `@RequestMapping`, `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`

作用：用于定义 API 的 HTTP 请求类型和 URL 路径。
常见用法：

@GetMapping("/user/{id}")
public User getUser(@PathVariable Long id) {// 代码
}

10. `@Consumes`, `@Produces`

作用：用于标注接口支持的内容类型，通常用于描述请求和响应的格式（如 JSON、XML 等）。
常见用法：

@Consumes("application/json")
@Produces("application/json")
@PostMapping("/user")
public ResponseEntity<User> createUser(@RequestBody User user) {// 代码
}

11. `@SwaggerDefinition`

作用：用来描述 Swagger 配置的元数据，如 API 的标题、版本、描述等。
常见用法：

@SwaggerDefinition(info = @Info(title = "用户管理 API", version = "1.0", description = "提供用户管理相关的操作")
)
public class UserController {// 控制器代码
}

12. `@ResponseStatus`

作用：用于指定 HTTP 响应的状态码，通常与 @ExceptionHandler 配合使用，定义异常的响应状态。
常见用法：

@ResponseStatus(value = HttpStatus.NOT_FOUND, reason = "用户未找到")
public class UserNotFoundException extends RuntimeException {// 代码
}

OpenAPI 和 Swagger 的关系

随着 OpenAPI Initiative 的出现，Swagger 成为了 OpenAPI 规范的工具之一。虽然 OpenAPI 规范变成了行业标准，但 Swagger 依然是最常用的工具集之一，并且支持 OpenAPI 3.0 规范。可以将 Swagger 理解为 OpenAPI 规范的工具实现，它包括了多种工具和框架来帮助开发者设计、文档化和测试 API。