Swagger 文档入门指南：一步一步构建 API 文档

Swagger、API 文档、OpenAPI、RESTful

简介：

swagger 是一种用于创建交互式 api 文档的开源工具。它使用 OpenAPI 规范来定义 API，并提供了一个 UI 来可视化 API。这使得开发人员可以更轻松地创建和维护 API 文档，并使 API 更容易被其他开发人员使用。

步骤 1：安装 Swagger

在开始使用 Swagger 之前，需要先在本地计算机上安装它。

• 对于 Windows 用户：

  • 您可以从官网下载 windows 版本的 Swagger。
  • 双击下载的文件，并按照安装向导进行安装。

• 对于 Mac 用户：

  • 您可以使用 Homebrew 来安装 Swagger。
  • 打开终端，并输入以下命令：

      brew install swagger

• 对于 Linux 用户：

  • 您可以在官网上找到适用于 linux 的 Swagger 安装说明。

步骤 2：创建 OpenAPI 规范

一旦安装了 Swagger，就可以开始创建 OpenAPI 规范了。OpenAPI 规范是一种 YAML 或 JSON 格式的文件，用于描述 API。

要创建 OpenAPI 规范，可以使用 Swagger 编辑器或任何其他文本编辑器。您也可以使用 Swagger 代码生成器来从现有代码中生成 OpenAPI 规范。

例如，以下是一个简单的 OpenAPI 规范：

openapi: 3.0.1
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get all users
      operationId: getUsers
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          fORMat: int64
        name:
          type: string
        email:
          type: string

步骤 3：使用 Swagger UI 生成文档

创建了 OpenAPI 规范之后，就可以使用 Swagger UI 来生成 API 文档。

要使用 Swagger UI，请按照以下步骤操作：

• 启动 Swagger UI：

  • 打开终端，并输入以下命令：

      swagger serve

  • 这将启动 Swagger UI，并将其托管在本地计算机上。

• 打开 Swagger UI：

  • 在浏览器中，输入以下 URL：

      Http://localhost:8080

  • 这将打开 Swagger UI。

• 导入 OpenAPI 规范：

  • 在 Swagger UI 中，点击 "Import" 按钮。
  • 选择 OpenAPI 规范文件，然后点击 "Open" 按钮。

• 查看 API 文档：

  • Swagger UI 将生成 API 文档。您可以使用该文档来查看 API 的端点、参数、响应和示例。

步骤 4：部署 Swagger 文档

创建了 API 文档之后，可以将其部署到生产环境中。

您可以使用以下方法来部署 Swagger 文档：

• 使用静态文件服务器：

  • 您可以使用 Nginx 或 Apache 等静态文件服务器来托管 Swagger 文档。
  • 只需将 Swagger 文档复制到静态文件服务器的根目录即可。

• 使用 CDN：

  • 您也可以使用 CDN 来托管 Swagger 文档。
  • 只需将 Swagger 文档上传到 CDN，然后将 CDN 的 URL 指向 Swagger 文档即可。

• 使用 API 管理平台：

  • 许多 API 管理平台都支持 Swagger 文档。
  • 您可以将 Swagger 文档导入到 API 管理平台中，然后使用平台提供的工具来管理和发布 API 文档。