新手也能秒会的Swagger3使用指南，开源项目极简上手！

API 文档的秘密武器：Swagger3 和 SpringDoc

作为一名开发者，生成清晰、全面的 API 文档至关重要。它们不仅使你的 API 对用户友好，而且还可以简化团队协作和提高可维护性。为此，Swagger3 和 SpringDoc 闪亮登场，成为 API 文档的强大工具。

什么是 Swagger3？

Swagger3 是一款开源的 API 文档生成工具，采用 OpenAPI 规范，一种标准的 API 语言。它使你可以快速生成 RESTful API 的文档，并且可以跨多种编程语言和工具使用。

如何在 Maven 中安装 Swagger3？

在你的项目中添加以下 Maven 依赖即可安装 Swagger3：

<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-annotations</artifactId>
  <version>1.6.4</version>
</dependency>

如何使用 Swagger3？

在安装 Swagger3 后，只需在你的代码中添加一些注释即可生成 API 文档。

• 使用 @Api 注解你的 API。
• 使用 @ApiOperation 注解 API 的每个操作。
• 使用 @ApiParam 注解描述 API 的每个参数。

什么是 SpringDoc？

SpringDoc 是一种基于 Swagger3 的 API 文档生成工具，提供更简洁的语法和更强大的功能。

如何在 Maven 中安装 SpringDoc？

在你的项目中添加以下 Maven 依赖即可安装 SpringDoc：

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>2.9.2</version>
</dependency>

如何使用 SpringDoc？

在安装 SpringDoc 后，只需在你的代码中添加一些注释即可生成 API 文档。

• 使用 @Api 注解描述你的 API。
• 使用 @ApiOperation 注解描述 API 的每个操作。
• 使用 @ApiParam 注解描述 API 的每个参数。

为何从 Swagger3 迁移到 SpringDoc？

我们建议你从 Swagger3 迁移到 SpringDoc，因为它具有更简洁的语法和更强大的功能。SpringDoc 可以帮助你更轻松地生成 API 文档。

代码示例

Swagger3

@Api(value = "用户 API")
public class UserController {

    @ApiOperation(value = "获取所有用户")
    @GetMapping("/users")
    public List<User> getAllUsers() {
        // ...
    }

    @ApiOperation(value = "获取特定用户")
    @GetMapping("/users/{id}")
    public User getUserById(@PathVariable Long id) {
        // ...
    }

    @ApiOperation(value = "创建新用户")
    @PostMapping("/users")
    public User createUser(@RequestBody User user) {
        // ...
    }
}

SpringDoc

@Api(value = "用户 API")
public class UserController {

    @ApiOperation(value = "获取所有用户", tags = {"用户"})
    @GetMapping("/users")
    public List<User> getAllUsers() {
        // ...
    }

    @ApiOperation(value = "获取特定用户", tags = {"用户"})
    @GetMapping("/users/{id}")
    public User getUserById(@PathVariable Long id) {
        // ...
    }

    @ApiOperation(value = "创建新用户", tags = {"用户"})
    @PostMapping("/users")
    public User createUser(@RequestBody User user) {
        // ...
    }
}

常见问题解答

• 问：我应该使用 Swagger3 还是 SpringDoc？
  答：我们建议使用 SpringDoc，因为它具有更简洁的语法和更强大的功能。
• 问：如何生成 SpringDoc 文档？
  答：只需在你的代码中添加 @Api、@ApiOperation 和 @ApiParam 注释即可。
• 问：SpringDoc 文档可以公开吗？
  答：是的，你可以通过 /swagger-ui/index.html 路由公开 SpringDoc 文档。
• 问：如何使用 SpringDoc 验证 API 请求？
  答：SpringDoc 使用 JSON Schema 验证 API 请求。
• 问：如何使用 SpringDoc 生成 API 客户端？
  答：SpringDoc 可以根据你的 API 文档生成 API 客户端。