Swagger 基础教程：构建专业级 API 文档
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 的使用
- 安装和配置 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。
- 设计和文档化 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。
- 自动生成代码
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 代码，并且可以根据需要进行修改和调整。
- 测试 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 的功能、性能和可靠性。
- 集成和部署
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 文档和测试页面。
知识扩展：
更多 Swagger 使用教程。
