1.Swagger 是什么？

简单来说，Swagger 是一套围绕 OpenAPI 规范构建的开源工具集，用于设计、构建、文档化和使用 RESTful Web 服务。

这里需要理解两个核心概念：

1. OpenAPI 规范 (以前叫 Swagger 规范)：

   • 这是一个 标准，一个通用的、与编程语言无关的接口描述格式（通常使用 YAML 或 JSON 文件），用于定义 RESTful API 的结构。
   • 它可以描述你的 API 有哪些接口（/users, /orders）、每个接口支持的 HTTP 方法（GET, POST, PUT, DELETE）、请求参数（路径参数、查询参数、请求体）、可能的响应状态码以及返回的数据格式（JSON, XML）等。
   • 打个比方：OpenAPI 文件就像一份建筑蓝图，它详细规定了 API 的每一个细节。

2. Swagger 工具集：

   • 这是一系列 工具，它们读取和理解遵循 OpenAPI 规范的“蓝图”文件，并在此基础上提供各种实用功能。
   • 核心工具包括：
     • Swagger UI：将 OpenAPI 规范文件可视化为一个交互式的 API 文档页面。
     • Swagger Editor：一个浏览器编辑器，用于编写和验证 OpenAPI 规范文件。
     • Swagger Codegen：一个代码生成器，可以根据 OpenAPI 规范文件自动生成服务器端代码和客户端 SDK。

总结关系： OpenAPI 是“规范/蓝图”，Swagger 是使用该蓝图的“工具”。

生动的比喻：

• OpenAPI 规范 就像是一份详细的建筑蓝图（定义了一切）。
• Swagger 就像是看蓝图的建筑师（Swagger UI）、画蓝图的工具（Swagger Editor）和根据蓝图自动预制墙体的机器（Swagger Codegen）。

2. Swagger 可以用来做什么？

Swagger 工具集主要解决了 API 开发中的四大核心问题：

1. API 设计与规划 (Design First)

   • 在写代码之前，先用 Swagger Editor 定义好 API 的接口、数据模型等。这有助于团队在开发初期就达成一致，避免后期返工。

2. 自动生成交互式 API 文档 (Documentation)

   • 这是 Swagger 最广为人知的功能。通过 Swagger UI，你可以自动生成一个美观、交互式的文档网站。
   • 优势：
     • 永远最新：文档与代码同步，只要代码更新，文档自动更新。
     • 可交互：开发者可以直接在文档页面上调用 API，输入参数并看到实时返回结果，无需使用 Postman 或 Curl 等外部工具。

3. 自动生成代码 (Code Generation)

   • 服务器端代码：根据 API 规范，自动生成不同语言（如 Java Spring, Python Flask, Node.js 等）的框架代码，你只需要实现业务逻辑即可。
   • 客户端 SDK：根据 API 规范，自动生成多种语言的客户端代码，方便前端、移动端或其他服务快速集成和调用你的 API。

4. 自动化测试与校验 (Testing)

   • 通过 Swagger UI 的“Try it out”功能，可以方便地进行手工测试。
   • 可以集成其他工具（如 Schemathesis, Dredd）基于 OpenAPI 规范进行自动化测试，确保 API 的实现与规范一致。

3. Swagger 怎么用？

使用 Swagger 主要有两种工作流：

工作流一：设计优先 (Design First)

这种方式强调先设计好 API 契约，再开始编码。

1. 设计：使用 Swagger Editor（在线或本地安装）编写你的 openapi.yaml 或 openapi.json 文件。
2. 生成代码：使用 Swagger Codegen，根据上一步的规范文件生成服务器端骨架代码。
3. 实现业务逻辑：在生成的骨架代码中填充具体的业务逻辑。
4. 集成 UI：在项目中集成 Swagger UI，让它指向你的 OpenAPI 规范文件。这样，当你的服务启动时，就可以通过一个 URL（如 http://localhost:8080/swagger-ui.html）访问到交互式文档。

例如：

• 使用 Swagger Editor：

  • 访问在线的 Swagger Editor。

  • 在左侧编辑器中，使用 YAML 语法编写你的 API 规范。

  • openapi: 3.0.0
    info:
      title: 简单用户API
      version: 1.0.0
    paths:
      /users/{id}:
        get:
          summary: 根据ID获取用户
          parameters:
            - name: id
              in: path
              required: true
              description: 用户的唯一标识符
              schema:
                type: integer
          responses:
            '200':
              description: 成功
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/User'
    components:
      schemas:
        User:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string
    

    编辑器右侧会实时渲染出 API 文档。

• 生成代码：

  • 在 Swagger Editor 中，可以点击 “Generate Server” 或 “Generate Client” 来下载相应语言的框架代码。
  • 或者使用命令行工具 Swagger Codegen。

• 其他流行框架的用法

  • Node.js (Express): 使用 swagger-jsdoc 和 swagger-ui-express 包。

  • npm install swagger-jsdoc swagger-ui-express
    

  • 通过 JSDoc 注释来定义 API，然后在 Express 中设置 Swagger UI 中间件。

  • .NET Core: 使用 Swashbuckle.AspNetCore NuGet 包，它是 .NET Core 的标配，用法与 Spring Boot 的 springdoc 非常相似。

工作流二：代码优先 (Code First)

这种方式是先写代码，然后从代码中自动生成 OpenAPI 规范。

1. 编码：像平常一样编写你的 API 控制器和模型。

2. 添加注解：在代码中使用特定的注解（例如 Java 的 SpringFox 或 SpringDoc 注解，.NET 的 Swashbuckle 属性）来描述你的 API。

   // SpringDoc 示例 (Java)
   @RestController
   public class UserController {
       @Operation(summary = "Get user by ID") // 描述这个操作
       @ApiResponse(responseCode = "200", description = "Found the user") // 描述响应
       @GetMapping("/users/{id}")
       public User getUser(@Parameter(description = "User ID") @PathVariable Long id) { // 描述参数
           // ... 业务逻辑
       }
   }
   

3. 自动生成文档：集成相应的库（如 SpringDoc for Spring Boot），它会在项目运行时，扫描这些注解，自动生成 OpenAPI 规范，并提供内嵌的 Swagger UI 端点。

目前，“代码优先”由于其开发便捷性，在实际项目中更为流行。

一个快速上手的例子（Spring Boot + SpringDoc）

Spring Boot 是目前最流行的 Java Web 框架之一，我们用它来演示“代码优先”工作流。

1. 添加依赖
   在你的 pom.xml 中添加 SpringDoc 依赖：

   <dependency>
       <groupId>org.springdoc</groupId>
       <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
       <version>2.1.0</version> <!-- 请使用最新版本 -->
   </dependency>
   

2. 编写一个简单的 Controller

   import io.swagger.v3.oas.annotations.Operation;
   import io.swagger.v3.oas.annotations.tags.Tag;
   import org.springframework.web.bind.annotation.*;
   
   @RestController
   @Tag(name = "用户管理", description = "用户的增删改查API") // 给API分组
   public class UserController {
   
       @Operation(summary = "根据ID获取用户") // 描述接口
       @GetMapping("/users/{id}")
       public String getUserById(@PathVariable Long id) {
           return "User with id: " + id;
       }
   
       @Operation(summary = "创建新用户")
       @PostMapping("/users")
       public String createUser(@RequestBody User user) { // 假设有一个User类
           return "User created: " + user.getName();
       }
   }
   

3. 启动并访问

   • 启动你的 Spring Boot 应用。
   • 打开浏览器，访问：http://localhost:8080/swagger-ui.html
   • 你会看到一个自动生成的、清晰的 API 文档页面。你可以点击 “users” 展开，看到你刚写的两个接口，并且可以点击 “Try it out” 按钮直接进行测试！

总结

对于初学者，建议从 代码优先 的方式开始，通过在现有项目中集成相关的 Swagger 库（如 SpringDoc for Spring Boot, Swashbuckle for .NET），可以最快地体验到它带来的巨大便利。