Ubuntu如何安装Swagger工具 - 问答

在Ubuntu上安装Swagger工具（以Swagger UI为例）
Swagger工具主要用于API文档的生成与可视化测试，常见的安装方式包括通过npm包管理器（适用于Node.js环境）或Docker容器（适用于隔离环境）。以下是详细步骤：

一、准备工作：更新系统并安装依赖

在安装Swagger前，需确保系统包列表最新，并安装必要的依赖（如Node.js、npm）：

sudo apt update && sudo apt upgrade -y  # 更新系统包
sudo apt install nodejs npm -y          # 安装Node.js和npm（Swagger UI的依赖）

二、方法一：通过npm安装Swagger UI（推荐）

1. 全局安装Swagger UI相关包

使用npm全局安装swagger-ui-express（用于Express框架集成）和yamljs（解析YAML格式的Swagger文档）：

sudo npm install -g swagger-ui-express yamljs

2. 创建Express应用并集成Swagger UI

初始化项目：创建一个新目录并初始化npm项目：

mkdir swagger-ui-example && cd swagger-ui-example
npm init -y  # 自动生成package.json文件

安装Express：添加Express框架作为项目依赖：
```
npm install express
```

创建Swagger文档：在项目根目录下创建swagger.yaml文件，定义API元数据（示例）：

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
  description: A simple API for demonstration
servers:
  - url: http://localhost:3000
paths:
  /users:
    get:
      summary: Get all users
      responses:
        200:
          description: A list of users

编写服务器代码：创建server.js文件，集成Swagger UI到Express应用：

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');

const app = express();
const swaggerDocument = YAML.load('./swagger.yaml'); // 加载Swagger文档

// 托管Swagger UI，访问路径为/api-docs
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running at http://localhost:${PORT}`);
  console.log(`Swagger UI available at http://localhost:${PORT}/api-docs`);
});

3. 启动应用并访问Swagger UI

运行以下命令启动Express服务器：

node server.js

打开浏览器，访问http://localhost:3000/api-docs，即可看到Swagger UI界面，展示swagger.yaml中定义的API文档。

三、方法二：使用Docker安装Swagger UI

若希望使用容器化环境，可通过Docker快速部署Swagger UI：

1. 安装Docker

若未安装Docker，执行以下命令安装：

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

2. 拉取Swagger UI镜像

从Docker Hub拉取官方Swagger UI镜像：

docker pull swaggerapi/swagger-ui

3. 运行Swagger UI容器

将本地的swagger.yaml文件挂载到容器中，并映射端口：

docker run -d -p 8080:8080 -v $(pwd)/swagger.yaml:/app/swagger.yaml --name swagger-ui swaggerapi/swagger-ui

-d：后台运行容器；
-p 8080:8080：将容器的8080端口映射到主机的8080端口；
-v $(pwd)/swagger.yaml:/app/swagger.yaml：将主机当前目录的swagger.yaml挂载到容器的/app目录。

4. 访问Swagger UI

打开浏览器，访问http://localhost:8080，即可查看Swagger UI界面。

注意事项

若使用npm安装时遇到权限问题，可在命令前添加sudo；
Swagger UI支持swagger.yaml（YAML格式）和swagger.json（JSON格式）两种文档格式，可根据需求选择；
若需自定义Swagger UI（如修改主题、添加认证），可参考Swagger UI官方文档。

0 赞

0 踩