Linux系统中Swagger工具使用教程

一、Swagger工具概述

Swagger（现更名为OpenAPI Specification）是一套用于设计、构建、文档化和使用RESTful API的开源框架。其核心组件包括：

• Swagger Editor：在线编辑OpenAPI规范的工具，支持实时语法检查和预览；
• Swagger UI：可视化展示API文档的Web界面，支持在线测试接口；
• Swagger Codegen：根据OpenAPI规范自动生成客户端SDK或服务器端代码框架。

本教程聚焦Linux环境下Swagger工具的安装、配置及核心功能使用。

二、Swagger安装

1. Docker容器部署（推荐）

Docker是Linux下部署Swagger的最简方式，无需处理依赖问题。

（1）安装Docker

若未安装Docker，可通过以下命令完成安装：

sudo apt-get update
sudo apt-get install -y docker.io
sudo systemctl start docker
sudo systemctl enable docker

（2）拉取Swagger镜像

分别拉取Swagger Editor（编辑规范）和Swagger UI（查看文档+测试）的官方镜像：

docker pull swaggerapi/swagger-editor:v4.15.5
docker pull swaggerapi/swagger-ui:v4.15.5

（3）运行Swagger容器

• 启动Swagger Editor容器，将容器8080端口映射到宿主机8080端口：

  docker run -d -p 8080:8080 swaggerapi/swagger-editor:v4.15.5
  

• 启动Swagger UI容器，将容器8080端口映射到宿主机8081端口：

  docker run -d -p 8081:8080 swaggerapi/swagger-ui:v4.15.5
  

（4）访问Swagger工具

• 打开浏览器，访问http://<服务器IP>:8080进入Swagger Editor（用于编写/编辑OpenAPI规范）；
• 访问http://<服务器IP>:8081进入Swagger UI（用于查看文档并测试接口）。

2. 传统安装方式（Node.js环境）

若需本地安装Swagger命令行工具，可通过Node.js的npm包管理器实现：

# 全局安装Swagger命令行工具
npm install -g swagger

安装完成后，可通过swagger --version验证是否安装成功。

三、OpenAPI规范编写

OpenAPI规范是Swagger的核心，定义了API的**端点（Endpoints）、参数（Parameters）、请求/响应（Requests/Responses）**等信息，格式为JSON或YAML（推荐YAML，更易读）。

示例：简单的用户管理API规范（YAML格式）

openapi: 3.0.0
info:
  title: 用户管理API
  version: 1.0.0
  description: 提供用户增删改查功能的RESTful API
servers:
  - url: http://localhost:8080/api
    description: 本地开发服务器
paths:
  /users:
    get:
      summary: 获取所有用户
      responses:
        '200':
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: 创建新用户
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: 用户创建成功
  /users/{id}:
    get:
      summary: 根据ID获取用户
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 成功返回用户信息
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        username:
          type: string
        email:
          type: string
          format: email

将上述内容保存为user-api.yaml，后续可通过Swagger Editor编辑或Swagger Codegen生成代码。

四、Swagger Editor使用

Swagger Editor是编写和预览OpenAPI规范的可视化工具，主要功能包括：

• 语法检查：实时提示YAML/JSON格式错误；
• 预览文档：自动生成Swagger UI风格的文档；
• 导出文件：将规范导出为JSON或YAML格式。

操作步骤

1. 打开浏览器访问http://<服务器IP>:8080，进入Swagger Editor界面；
2. 点击左上角File → Import File，选择本地编写的user-api.yaml文件；
3. 编辑规范时，右侧会实时显示生成的API文档；
4. 编辑完成后，点击File → Save As导出为JSON/YAML文件。

五、Swagger UI使用

Swagger UI是展示API文档并支持在线测试的核心工具，主要功能包括：

• 可视化文档：以树形结构展示API端点、参数、响应等信息；
• 在线测试：通过“TRY IT OUT”按钮直接发送请求，查看响应结果；
• 授权管理：支持API密钥、OAuth2等认证方式的配置。

操作步骤

1. 打开浏览器访问http://<服务器IP>:8081，进入Swagger UI界面；
2. 点击右上角Explore按钮，选择本地user-api.yaml文件（或输入远程规范URL）；
3. 浏览左侧菜单，找到目标端点（如/users/{id}/get）；
4. 点击端点名称，右侧会显示该端点的详细信息；
5. 输入参数（如id: 1），点击Try it out按钮，查看响应结果（如下图所示）。

六、代码自动生成（Swagger Codegen）

Swagger Codegen可根据OpenAPI规范自动生成客户端SDK（如Java、Python）或服务器端代码框架（如Spring Boot、Node.js），减少重复劳动。

示例：生成Node.js服务器端代码

# 使用Swagger Editor生成的user-api.json文件（需先导出）
swagger generate server -i user-api.json -l nodejs-server -o ./user-api-server

参数说明

• -i：指定OpenAPI规范文件的路径（JSON或YAML）；
• -l：指定生成代码的编程语言（如java、python、spring）；
• -o：指定生成代码的输出目录。

生成完成后，进入输出目录（如./user-api-server），可通过npm install安装依赖，npm start启动服务器。

七、常见问题解决

1. Docker容器无法访问：检查防火墙是否放行映射端口（如8080、8081），或通过docker ps确认容器是否正常运行；
2. Swagger Editor语法报错：根据右侧错误提示修改YAML文件（如缩进错误、字段缺失）；
3. Swagger UI无法加载规范：确保规范文件路径正确（如file:///path/to/user-api.yaml或远程URL可访问）。

通过以上步骤，可在Linux系统上完成Swagger工具的安装、配置及核心功能使用，实现API文档的可视化、在线测试及代码自动生成，提升API开发效率。