Swagger在Debian怎用

下面分**“用 Swagger 来写/展示 API 文档”和“在 Debian 上运行 Swagger 工具”**两部分说，都是 Debian（含 Ubuntu）环境下最常见的用法。

一、Swagger 是什么（先理清概念）

Swagger 现在通常指 OpenAPI + Swagger 工具链：

OpenAPI：API 描述规范（yaml / json）
Swagger UI：可视化 API 页面
Swagger Editor：写 OpenAPI 文档
Swagger Codegen / OpenAPI Generator：生成代码

二、在 Debian 上用 Swagger UI（最常用）

方式 1：用 Docker（最简单 ✅ 推荐）

sudo apt update
sudo apt install docker.io -y
sudo systemctl enable --now docker

docker run -p 8080:8080 \
  -e SWAGGER_JSON=/foo/openapi.yaml \
  -v $PWD:/foo \
  swaggerapi/swagger-ui

浏览器访问：

http://localhost:8080

方式 2：直接用静态文件（无 Docker）

sudo apt install nginx -y

cd /var/www/html
git clone https://github.com/swagger-api/swagger-ui.git
cp swagger-ui/dist/* .

# 修改 index.html 中的 url 指向你的 openapi.yaml

访问：

http://<debian-ip>/

三、用 Swagger Editor（写 API 文档）

Docker 方式

docker run -p 8081:8080 swaggerapi/swagger-editor

访问：

http://localhost:8081

四、Node 项目中使用 Swagger（开发 API）

1️⃣ 安装

sudo apt install nodejs npm -y
npm init -y
npm install swagger-ui-express yamljs

2️⃣ Express 示例

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

const swaggerDocument = YAML.load("./swagger.yaml");
const app = express();

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

app.listen(3000);

访问：

http://localhost:3000/api-docs

五、用 Swagger Codegen（生成客户端/服务端代码）

sudo apt install default-jre -y
wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.41/swagger-codegen-cli-3.0.41.jar

java -jar swagger-codegen-cli-3.0.41.jar generate \
  -i openapi.yaml \
  -l python \
  -o ./client

六、常见问题

✅ Debian 无图形界面也能跑（Server 版）
✅ Swagger UI 只是静态页面
❌ Swagger ≠ 自动测试（那是 Postman / Dredd）

如果你告诉我：

是 写文档 / 看文档 / 自动生成代码
用的 语言（Java / Python / Node）
是否 有 Docker

我可以直接给你一份可复制粘贴的配置。