Swagger教程：新手入门全攻略

本文详细介绍了如何使用Swagger，一个流行的API文档工具，来创建和维护RESTful API，包括其安装、配置、文档编写和测试等步骤。通过学习，开发者能够轻松掌握Swagger的使用方法，提高API开发和维护的效率。

什么是Swagger

Swagger 是一个流行的 API 文档工具，它提供了一套规范和完整的框架，用于描述、生成、校验 RESTful 风格 Web 服务，支持多种编程语言，如 Java、Python、Ruby、PHP、C# 等。通过使用 Swagger，开发人员可以轻松地创建、维护、使用和理解 RESTful API。

Swagger的作用和优势

Swagger 的主要作用是帮助开发人员快速和准确地创建和理解 API。它不仅简化了 API 的文档编写过程，还提供了强大的工具来测试和调试 API。Swagger 可以自动生成 API 文档，通过交互式界面测试 API，并从 API 文档生成客户端代码和服务器端代码。具体优势如下：

1. 自动化的文档生成：Swagger 可以自动生成 API 文档，这使得 API 的维护变得更加简单。例如，可以使用 @EnableSwagger2 注解启用 Swagger 功能，并配置 Swagger 基本信息，如 API 标题、描述、版本等。

2. 交互式 API 文档：Swagger UI 允许用户通过一个交互式界面来测试 API，这对于 API 的测试和调试非常有用。例如，用户可以访问 http://localhost:8080/swagger-ui.html 来测试 API。

3. 代码生成：Swagger 可以从 API 文档生成客户端代码和服务器端代码。例如，通过 Swagger Editor 编写 API 文档，并将其保存为 JSON 或 YAML 文件，然后在项目中引入生成的 Swagger JSON 文件，配置 Swagger 读取该文件。

Swagger与API文档的关系

API 文档是描述 API 的功能、参数、返回值以及使用方式的一种文档。Swagger 是一种流行的 API 文档工具，它提供了一套规范和完整的框架来描述 API。通过使用 Swagger，开发人员可以生成规范化的 API 文档，并通过 Swagger UI 提供交互式的测试界面。这种文档不仅提高了 API 的可读性，还便于维护和使用。

下载和安装Swagger工具

Swagger 工具可以通过多种方式获取，其中最流行的是使用 Swagger Codegen 和 Swagger Editor。以下是安装步骤：

1. 下载 Swagger Editor：

   • 访问 Swagger Editor 的官网：https://editor.swagger.io/
   • 直接在浏览器中打开 Swagger Editor 的在线版本，无需下载安装。
2. 下载 Swagger Codegen：
   • 通过 Maven 下载 Swagger Codegen：在 pom.xml 文件中添加以下依赖：

     <dependency>
     <groupId>io.swagger.codegen.v3</groupId>
     <artifactId>swagger-codegen-cli</artifactId>
     <version>3.0.16</version>
     </dependency>

   • 使用 Gradle 下载 Swagger Codegen：在 build.gradle 文件中添加以下依赖：

     implementation 'io.swagger.codegen.v3:swagger-codegen-cli:3.0.16'

配置Swagger的基本步骤

配置 Swagger 的基本步骤包括：

1. 添加 Swagger 依赖：

   • 在项目中添加相应的 Swagger 依赖，例如 Maven 或 Gradle 依赖。

2. 配置 Swagger 配置文件：

   • 创建 SwaggerConfig 类，并配置 Swagger 的基本信息，例如 API 标题、描述、版本等。

3. 启用 Swagger 文档：

   • 在 Spring Boot 项目中，可以通过 @EnableSwagger2 注解来启用 Swagger 文档。

   • 示例代码：

     @Configuration
     @EnableSwagger2
     public class SwaggerConfig {
     
      @Bean
      public Docket api() {
          return new Docket(DocumentationType.SWAGGER_2)
                  .select()
                  .apis(RequestHandlerSelectors.any())
                  .paths(PathSelectors.any())
                  .build();
      }
     }

配置Swagger UI和文档

配置 Swagger UI 和文档的步骤如下：

1. 配置 Swagger UI：

   • 在项目的 src/main/resources 目录下创建 swagger-ui.html 文件，并引入 Swagger UI 的相关资源。
   • 配置 web.xml 或 application.yml 文件来启动 Swagger UI。

2. 生成 Swagger JSON 文件：

   • 通过 Swagger Editor 编写 API 文档，并将其保存为 JSON 或 YAML 文件。
   • 在项目中引入生成的 Swagger JSON 文件，并配置 Swagger 读取该文件。
3. 启动 Swagger UI：
   • 访问项目中的 Swagger UI 界面，检查是否可以正确显示 API 文档和交互式测试界面。

示例代码：
在 Spring Boot 项目中配置 Swagger 的 SwaggerConfig 类：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

编写简单的Swagger API定义

编写 Swagger API 定义时，需要遵循 Swagger 的规范格式。以下是简单的 Swagger 定义示例：

swagger: "2.0"
info:
  version: "1.0.0"
  title: "简单API测试"
  description: "这是一个简单的API文档示例"
basePath: "/api"
schemes:
  - "http"
  - "https"
produces:
  - "application/json"
paths:
  /hello:
    get:
      summary: "获取消息"
      description: "返回简单的问候消息"
      operationId: "getHello"
      responses:
        200:
          description: "成功"
          schema:
            type: "string"
            example: "Hello, World!"

使用Swagger编辑器验证API定义

Swagger Editor 提供了一个在线编辑器，可以用来验证和测试 API 定义。以下是使用 Swagger Editor 验证 API 定义的步骤：

1. 打开 Swagger Editor：https://editor.swagger.io/
2. 将上面的 Swagger 定义粘贴到编辑器中。
3. 点击右上角的 Try it out 按钮来测试 API 定义是否正确。

4. 验证结果：

   • 图形界面友好，响应时间符合预期
   • 查询结果与预期一致
   • 所有操作均返回预期的 JSON 数据

生成Swagger JSON或YAML文件

生成 Swagger JSON 或 YAML 文件的步骤如下：

1. 在 Swagger Editor 中，将 API 定义保存为 JSON 或 YAML 文件。
2. 将生成的文件保存到项目的指定目录下，例如 src/main/resources。

示例代码：
生成的 swagger.json 文件：

{
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "简单API测试",
    "description": "这是一个简单的API文档示例"
  },
  "basePath": "/api",
  "schemes": [
    "http",
    "https"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/hello": {
      "get": {
        "summary": "获取消息",
        "description": "返回简单的问候消息",
        "operationId": "getHello",
        "responses": {
          "200": {
            "description": "成功",
            "schema": {
              "type": "string",
              "example": "Hello, World!"
            }
          }
        }
      }
    }
  }
}

API、资源、操作的基本概念

在 Swagger 中，API、资源、操作是三种基本概念：

• API：API 是一组定义良好的接口，这些接口定义了客户端和服务器之间的交互方式。Swagger 定义了一个 API 的所有端点和操作。
• 资源：资源是 API 中的一个具体实体，例如用户、订单、商品等。资源通常通过 URL 来标识和访问。
• 操作：操作定义了客户端可以对资源执行的具体行为，例如查询、创建、更新和删除等。

标签、描述、参数等常用术语

Swagger 中常用的一些术语包括：

• 标签：标签用于对 API 进行分类，可以帮助用户更好地理解 API 的组织方式。
• 描述：描述用于解释 API、资源或操作的具体内容和行为。
• 参数：参数用于定义操作的输入和输出，包括路径参数、查询参数、头参数和表单参数等。

使用注解描述API的各个部分

在 Swagger 中，可以使用 Java 注解来描述 API 的不同部分。以下是一些常用的注解：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponses;
import io.swagger.annotations.ApiResponse;

@Api(value = "User API", description = "操作用户")
public class UserController {

    @ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "成功", response = User.class),
        @ApiResponse(code = 401, message = "未授权"),
        @ApiResponse(code = 403, message = "禁止"),
        @ApiResponse(code = 404, message = "未找到用户")
    })
    @GetMapping("/users/{userId}")
    public ResponseEntity<User> getUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long userId) {
        User user = userService.getUserById(userId);
        return ResponseEntity.ok(user);
    }
}

示例代码：
使用注解描述 API 的 UserController 类：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponses;
import io.swagger.annotations.ApiResponse;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;

@Api(value = "User API", description = "操作用户")
public class UserController {

    @ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "成功", response = User.class),
        @ApiResponse(code = 401, message = "未授权"),
        @ApiResponse(code = 403, message = "禁止"),
        @ApiResponse(code = 404, message = "未找到用户")
    })
    @GetMapping("/users/{userId}")
    public ResponseEntity<User> getUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long userId) {
        User user = userService.getUserById(userId);
        return ResponseEntity.ok(user);
    }
}

安全性设置（如OAuth2、JWT）

Swagger 支持多种安全性设置，包括 OAuth2 和 JWT。以下是如何在 Swagger 中配置安全性设置的示例：

OAuth2 安全性设置

securityDefinitions:
  oauth2:
    type: "oauth2"
    flow: "accessCode"
    authorizationUrl: "http://localhost:8080/oauth/authorize"
    tokenUrl: "http://localhost:8080/oauth/token"
    scopes:
      read: "Read access to protected resources"
      write: "Write access to protected resources"

paths:
  /api/users:
    get:
      summary: "获取用户列表"
      security:
        - oauth2: ["read", "write"]

JWT 安全性设置

securityDefinitions:
  jwt:
    type: "apiKey"
    name: "Authorization"
    in: "header"

paths:
  /api/users:
    get:
      summary: "获取用户列表"
      security:
        - jwt: []

定义复杂的数据模型

在 Swagger 中定义复杂的数据模型时，可以通过 Schema 对象来描述数据结构。以下是一个简单的用户数据模型示例：

definitions:
  User:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
      name:
        type: "string"
      email:
        type: "string"
        format: "email"
      age:
        type: "integer"
        format: "int32"

使用Swagger UI进行测试和调试

Swagger UI 提供了一个交互式的界面，可以用来测试和调试 API。以下是如何使用 Swagger UI 进行测试的步骤：

1. 访问 Swagger UI 界面：访问项目中的 Swagger UI 界面，例如 http://localhost:8080/swagger-ui.html。
2. 选择 API 端点：在 Swagger UI 中选择要测试的 API 端点。
3. 输入参数：根据需要输入参数并进行测试。
4. 查看响应：查看请求的响应结果。

示例代码：
定义一个简单的用户数据模型：

definitions:
  User:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
      name:
        type: "string"
      email:
        type: "string"
        format: "email"
      age:
        type: "integer"
        format: "int32"

定义一个 API 端点并使用 Swagger UI 进行测试：

paths:
  /users:
    get:
      summary: "获取用户列表"
      responses:
        200:
          description: "成功"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/User"

跟踪API变更和版本控制

跟踪 API 变更和版本控制是维护 Swagger 文档的重要部分。以下是跟踪 API 变更和版本控制的步骤：

1. 记录变更历史：记录每次 API 变更的历史，包括变更的内容、日期和负责人。
2. 版本控制：为每个 API 变更发布一个新的版本，并更新文档中的版本信息。
3. 使用注释：在文档中使用注释来标记 API 的变更历史，便于未来查找和维护。

示例代码：
记录 API 变更历史：

info:
  version: "1.0.0"
description: |
  这是一个简单的API文档示例
  变更历史:
  - 2023-01-01: 初始版本发布
  - 2023-02-01: 增加了用户信息查询功能
  - 2023-03-01: 优化了用户信息查询性能

同步代码生成的Swagger文档

同步代码生成的 Swagger 文档可以确保 API 文档与实际代码保持一致。以下是同步代码生成 Swagger 文档的步骤：

1. 编写代码生成器：编写代码生成器来自动从实际代码生成 Swagger 文档。
2. 定期同步：定期运行代码生成器来同步代码生成的 Swagger 文档。
3. 验证生成的文档：验证生成的 Swagger 文档是否正确反映了实际代码的变化。

示例代码：
编写代码生成器来生成 Swagger 文档：

import io.swagger.models.Swagger;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.Paths;
import io.swagger.v3.oas.models.Operation;
import io.swagger.v3.oas.models.media.Schema;
import io.swagger.v3.oas.models.responses.ApiResponse;
import io.swagger.v3.oas.models.responses.ApiResponses;

public class SwaggerGenerator {

    public static void main(String[] args) {
        OpenAPI openAPI = new OpenAPI();
        Paths paths = new Paths();
        openAPI.setPaths(paths);

        Operation operation = new Operation();
        operation.setSummary("获取用户信息");
        operation.setResponses(new ApiResponses().addApiResponse("200", new ApiResponse().description("成功")));
        paths.addProperties("/users/{userId}", operation);

        Schema<String> userSchema = new Schema<>();
        userSchema.setType("string");
        operation.addResponseHeaders(new HashMap<String, io.swagger.v3.oas.models.headers.Header>() {{
            put("X-Auth-User", new io.swagger.v3.oas.models.headers.Header().setDescription("用户认证信息"));
        }});

        System.out.println(openAPI);
    }
}

管理Swagger文档的发布和撤销

管理 Swagger 文档的发布和撤销可以确保文档的准确性和一致性。以下是管理 Swagger 文档发布和撤销的步骤：

1. 发布文档：当文档准备就绪并经过验证后，发布文档。
2. 撤销文档：如果发现文档存在错误或变化，及时撤销文档并重新发布。
3. 使用版本控制：使用版本控制来记录文档的发布和撤销历史。

示例代码：
发布和撤销文档的示例：

info:
  version: "1.0.0"
description: "这是一个简单的API文档示例"
# 发布文档
paths:
  /users:
    get:
      summary: "获取用户列表"
      responses:
        200:
          description: "成功"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: "#/components/schemas/User"

# 撤销文档
# paths:
#   /users:
#     get:
#       summary: "获取用户列表"
#       responses:
#         200:
#           description: "成功"
#           content:
#             application/json:
#               schema:
#                 type: "array"
#                 items:
#                   $ref: "#/components/schemas/User"

总结：
通过以上步骤，您可以完全掌握 Swagger 的安装、配置、使用、维护和更新。遵循这些步骤，您可以确保 API 文档的准确性和一致性，从而提高 API 的开发和维护效率。