Swagger 核心组件

Swagger 是一套围绕 OpenAPI 规范构建的开源工具集，用于设计、构建、记录和使用 RESTful API。

Swagger 提供了一种标准化的方式来描述 API 的结构，使得开发者和机器都能理解 API 的功能而无需访问源代码或其他文档。

Swagger 的核心价值在于：

  • 标准化：提供统一的 API 描述格式
  • 可视化：自动生成交互式 API 文档
  • 可测试性：允许直接在文档中测试 API 端点
  • 代码生成：支持多种语言的客户端和服务端代码生成

Swagger 核心组件

组件输入输出适用阶段
Swagger Editor手动编写 YAML/JSON实时预览的 API 文档API 设计阶段
Swagger UIOpenAPI 文件交互式网页文档开发/测试阶段
Swagger CodegenOpenAPI 文件客户端/服务端代码前后端协作阶段

组件协作流程图：

Swagger Editor（设计API）  
  ↓  
OpenAPI 规范文件（YAML/JSON）  
  ↓  
Swagger UI（展示文档） 或 Swagger Codegen（生成代码）

Swagger 核心组件详解

1. Swagger Editor

Swagger Editor 是基于浏览器的可视化编辑器，用于编写和实时预览 OpenAPI 规范（YAML/JSON 格式）。

Swagger Editor 提供语法高亮、自动补全和错误校验。

Swagger Editor 代码生成、保存和导出功能现已加入 SmartBear API Hub，访问地址：https://try.platform.smartbear.com/new-organization。

使用场景：

  • 快速设计 API 原型
  • 学习 OpenAPI 规范语法

访问在线编辑器 Swagger Editor：https://editor.swagger.io/

输入以下 YAML 代码（定义一个简单的 GET /users 接口）：

实例

span style="color: green;">
openapi: 3.0.3
info:
  title: RUNOOB 用户管理系统
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

右侧将实时渲染出 API 文档和交互式 UI。

Swagger UI

Swagger UI 将 OpenAPI 规范转换为可视化交互式文档，支持直接在浏览器中测试 API。

Swagger UI 会自动生成请求示例、响应模型和调试界面。

Swagger UI: https://swagger.io/tools/swagger-ui/

使用场景：

  • 团队共享 API 文档
  • 前端开发者调试接口

集成示例（以 Node.js 为例）,安装依赖：

npm install swagger-ui-express swagger-jsdoc

创建 swagger.js 配置文件：

实例

const swaggerJSDoc = require('swagger-jsdoc');
const options = {
  definition: {
    openapi: '3.0.0',
    info: { title: '用户API', version: '1.0.0' },
  },
  apis: ['./routes/*.js'], // 扫描路由文件中的注释
};
const swaggerSpec = swaggerJSDoc(options);
module.exports = swaggerSpec;

在 Express 中挂载 UI：

实例

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

const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

访问 http://localhost:3000/api-docs 查看文档。

Swagger Codegen

Swagger Codegen 根据 OpenAPI 规范自动生成客户端 SDK（如 Java、Python）或服务端桩代码（如 Spring、Flask）。

Swagger Codegen 支持自定义模板。

下载页面：https://swagger.io/tools/swagger-codegen/

使用场景：

  • 快速生成 API 调用的客户端代码
  • 服务端接口自动化开发

操作示例（命令行生成 Java 客户端）, 下载 Swagger Codegen CLI：

wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.35/swagger-codegen-cli-3.0.35.jar -O swagger-codegen-cli.jar

生成代码：

java -jar swagger-codegen-cli.jar generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -l java \
  -o ./petstore-api-client

Swagger Hub（可选扩展）

Swagger Hub 是 Swagger 的云端平台，提供协作设计、版本管理和托管文档。

Swagger Hub 支持团队协作和 API 生命周期管理。

使用场景：

  • 企业级 API 项目管理
  • 需要在线协作的分布式团队

访问地址：https://swagger.io/api-hub/