写给全栈工程师的 Swagger 基础教程

Swagger 是一个开源的 API 设计和文档工具，可以帮助全栈工程师更快、更简单地设计、构建、文档化和测试 RESTful API。本篇文章将为全栈工程师介绍 Swagger 的基础知识和使用方法，以及如何使用 Swagger 设计、文档化和测试 RESTful API。

一、Swagger 简介

Swagger 是一个开源的 API 设计和文档工具，由 Tony Tam 创建于 2010 年。Swagger 提供了一种简单、易于使用的方式来设计、构建、文档化和测试 RESTful API。Swagger 可以自动生成交互式 API 文档、客户端 SDK、服务器 stub 代码等，从而使开发人员更容易地开发、测试和部署 API。

Swagger 的主要组成部分包括：

• OpenAPI 规范：Swagger 采用 OpenAPI 规范（前身是 Swagger 规范），用于定义和描述 RESTful API。OpenAPI 规范使用 JSON 或 YAML 格式编写，包含 API 的基本信息、端点、参数、请求和响应等信息。
• Swagger Codegen：Swagger Codegen 是一个代码生成器，可以从 OpenAPI 规范自动生成客户端 SDK 和服务器 stub 代码。
• Swagger UI：Swagger UI 是一个基于 HTML、CSS 和 JavaScript 的可交互的 API 文档界面。Swagger UI 可以自动生成 API 文档，让用户可以轻松地浏览、理解和测试 API。

二、Swagger 的使用

1、安装和配置 Swagger

Swagger 可以在许多编程语言和框架中使用，例如 Java、Python、Node.js、Ruby、PHP 等。不同的编程语言和框架需要使用不同的 Swagger 工具。在本文中，我们将使用 Swagger 的 Node.js 版本，即 Swagger Express。

首先，需要在全局安装 Swagger：

npm install -g swagger

然后，在项目目录下创建一个 Swagger 项目：

swagger project create my-api

接下来，进入 my-api 目录，并启动 Swagger：

cd my-api
swagger project start

此时，Swagger 就已经成功安装和配置好了。我们可以在浏览器中访问 http://localhost:10010/docs 来查看 Swagger UI。

2、设计和文档化 API

Swagger 使用 OpenAPI 规范来定义和描述 RESTful API。OpenAPI 规范使用 JSON 或 YAML 格式编写，包含 API 的基本信息、端点、参数、请求和响应等信息。

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

swagger: "2.0"
info:
  title: "My API"
  version: "1.0.0"
paths:
  /hello:
    get:
      summary: "Say hello"
      description: "Returns a greeting message"
      produces:
        - "text/plain"
      responses:
        200:
          description: "Successful operation"
          schema:
            type: "string

在上面的示例中，我们定义了一个 API，它有一个 /hello 端点，并使用 GET 请求方法。在 /hello 端点上，我们定义了一个摘要、描述、生产的响应格式、响应代码和返回的数据类型等信息。

在实际的开发中，我们需要根据具体的需求来设计和文档化 API。可以使用 Swagger Editor 来创建和编辑 OpenAPI 规范，然后使用 Swagger UI 生成交互式 API 文档。

以下是一个使用 Swagger Editor 创建 OpenAPI 规范的示例：

swagger: "2.0"
info:
  title: "Pet Store API"
  version: "1.0.0"
paths:
  /pets:
    get:
      summary: "List all pets"
      responses:
        200:
          description: "Successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Pet"
    post:
      summary: "Create a new pet"
      parameters:
        - name: "pet"
          in: "body"
          required: true
          schema:
            $ref: "#/definitions/NewPet"
      responses:
        200:
          description: "Successful operation"
          schema:
            $ref: "#/definitions/Pet"
definitions:
  Pet:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
      name:
        type: "string"
  NewPet:
    type: "object"
    properties:
      name:
        type: "string"

在上面的示例中，我们定义了一个 Pet Store API，它有一个 /pets 端点，使用 GET 和 POST 请求方法。在 GET 方法中，我们定义了一个摘要、响应信息和返回的数据类型等信息。在 POST 方法中，我们定义了一个摘要、参数、响应信息和返回的数据类型等信息。我们还定义了两个数据模型：Pet 和 NewPet。

3、自动生成代码

Swagger Codegen 可以根据 OpenAPI 规范自动生成客户端 SDK 和服务器 stub 代码。Swagger Codegen 支持多种编程语言和框架，例如 Java、Python、Node.js、Ruby、PHP 等。Swagger Codegen 可以使用命令行工具或者 API 来生成代码。

以下是使用 Swagger Codegen 生成 Node.js 服务器 stub 代码的示例：

swagger-codegen generate \
  -i petstore.yaml \
  -l nodejs-server \
  -o my-server

在上面的示例中，我们指定了输入的 OpenAPI 规范文件、代码生成器的语言和框架、以及输出的目录。Swagger Codegen 将会自动生成 Node.js 服务器 stub 代码，并且可以根据需要进行修改和调整。

4、测试 API

Swagger UI 提供了一个集成的测试工具，可以帮助开发人员测试 API 的功能、性能和可靠性。Swagger UI 中提供了一个测试页面，允许开发人员使用各种 HTTP 请求方法来测试 API 的不同端点。

以下是一个使用 Swagger UI 测试 API 的示例：

首先，在浏览器打开 Swagger UI，找到要测试的 API 端点，例如 /pets。然后，选择一个 HTTP 请求方法，例如 GET 方法。在 Swagger UI 中，我们可以看到该 API 的摘要、参数、响应和返回的数据等信息。

接下来，我们可以在 Swagger UI 中输入参数值，并点击“Try it out”按钮来测试 API。Swagger UI 将会向该 API 端点发送请求，并显示响应结果和状态码。开发人员可以使用 Swagger UI 来测试 API 的不同端点和不同参数，以确保 API 的功能、性能和可靠性。

5、集成和部署

Swagger 可以与许多流行的开发和部署工具（如 Git、Jenkins、Docker 等）集成，以便更容易地部署和管理 API。Swagger 可以自动生成 Swagger UI，使开发人员可以直接从浏览器访问 API 文档和测试页面。

例如，我们可以将 Swagger UI 集成到 Node.js 服务器中：

const express = require('express');
const app = express();

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

在上面的示例中，我们使用 Express 框架来创建一个 Node.js 服务器，并将 Swagger UI 集成到 /api-docs 端点。我们还加载了一个 swagger.json 文件，该文件包含了我们创建的 OpenAPI 规范。使用 Swagger UI，我们可以从浏览器访问 /api-docs 端点，并查看 API 文档和测试页面。

对于全栈工程师我们有适合的 API 一体化工具推荐：Apifox 是一个基于云的 API 设计和文档工具，具有许多强大的功能和工具，可以帮助全栈工程师更轻松、更快速地设计、构建、文档化和测试 RESTful API。Apifox 的主要功能包括：自动化文档生成、实时协作、代码生成、API 测试和监控等。使用 Apifox，全栈工程师可以轻松地创建、共享和测试 API，从而提高开发效率和项目质量，帮助你更轻松地开发出满足 OpenAPI 规范的 API。

这里是 Apifox 提供的最佳实践。

1. 前端（或后端）在 Apifox 上定好接口文档初稿。
2. 前后端 一起评审、完善接口文档，定好接口用例。
3. 前端 使用系统根据接口文档自动生成的 Mock 数据进入开发，无需手写 mock 规则。
4. 后端 使用接口用例 调试开发中接口，只要所有接口用例调试通过，接口就开发完成了。如开发过中接口有变化，调试的时候就自动更新了文档，零成本的保障了接口维护的及时性。
5. 后端 每次调试完一个功能就保存为一个接口用例。
6. 测试人员 直接使用接口用例测试接口。
7. 所有接口开发完成后，测试人员（也可以是后端）使用集合测试功能进行多接口集成测试，完整测试整个接口调用流程。
8. 前后端 都开发完，前端从Mock 数据切换到正式数据，联调通常都会非常顺利，因为前后端双方都完全遵守了接口定义的规范。

知识扩展：

• 怎么使用 Swagger UI：详细介绍和使用指南
• 如何使用 Swagger Editor 编写 API 文档