怎么在Linux使用Swagger

在 Linux 上使用 Swagger，通常取决于你是 查看/调试 API，还是 生成/开发 API。下面按常见场景给你一套完整说明。

一、Swagger 是什么（先明确）

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

OpenAPI：API 描述规范（YAML / JSON）
Swagger UI：可交互的 API 文档页面
Swagger Editor：编写 OpenAPI 文件
Swagger Codegen / OpenAPI Generator：代码生成工具

二、在 Linux 上快速使用 Swagger UI（最常见）

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

docker run -p 8080:8080 swaggerapi/swagger-ui

然后浏览器访问：

http://localhost:8080

你可以：

在页面顶部 URL 中输入你的 openapi.yaml 或 openapi.json
或把 API 文件挂载进去

挂载本地 API 文件

docker run -p 8080:8080 \
  -v $(pwd)/openapi.yaml:/openapi.yaml \
  -e SWAGGER_JSON=/openapi.yaml \
  swaggerapi/swagger-ui

✅ 方式 2：直接下载 Swagger UI（无 Docker）

wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v5.17.14.tar.gz
tar -zxvf v5.17.14.tar.gz
cd swagger-ui-5.17.14/dist
python3 -m http.server 8080

浏览器访问：

http://localhost:8080

修改 swagger-initializer.js 中的 URL 指向你的 API 文档。

三、使用 Swagger Editor（编写 API）

✅ Docker 方式

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

访问：

http://localhost:8081

适合：

手写 OpenAPI
校验语法
实时预览

四、在 Linux 后端项目中使用 Swagger（开发）

1️⃣ Java（Spring Boot）✅ 最常见

依赖（Springfox 已过时，推荐 springdoc）

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.3.0</version>
</dependency>

访问：

http://localhost:8080/swagger-ui.html

2️⃣ Python（FastAPI ✅ 原生支持）

pip install fastapi uvicorn

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

启动：

uvicorn main:app --reload

访问：

http://localhost:8000/docs

3️⃣ Node.js（Express）

npm install swagger-ui-express swagger-jsdoc

const express = require("express");
const swaggerJsdoc = require("swagger-jsdoc");
const swaggerUi = require("swagger-ui-express");

const app = express();

const spec = swaggerJsdoc({
  definition: {
    openapi: "3.0.0",
    info: { title: "API", version: "1.0.0" }
  },
  apis: ["./index.js"]
});

app.use("/docs", swaggerUi.serve, swaggerUi.setup(spec));
app.listen(3000);

访问：

http://localhost:3000/docs

五、Swagger 命令行工具（Linux 常用）

Swagger Codegen

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

生成前端/后端代码：

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

六、常见问题

❓ Linux 没有浏览器怎么办？

用 远程访问
或用 curl 查看 JSON：

curl http://localhost:8080/v3/api-docs

❓ Swagger 和 OpenAPI 区别？

名称	说明
OpenAPI	API 规范
Swagger	工具实现

七、我可以帮你进一步做什么？

你可以直接告诉我：

✅ 你用的是 哪种语言 / 框架
✅ 是 查看别人的 API 还是 给自己项目加 Swagger
✅ 是否 必须离线 / 内网环境

我可以给你 精确到命令级别 的教程。