Swagger在Linux上怎么用

在 Linux 上使用 Swagger，通常取决于你是查看/调试 API，还是生成/开发 API。下面按最常见的几种场景给你一个清晰、实用的说明。

一、Swagger 是什么？

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

• 描述 REST API（OpenAPI 规范）
• 自动生成文档
• 在线调试接口

常见工具：

• Swagger Editor：写 API 文档
• Swagger UI：展示和调试 API
• Swagger Codegen / OpenAPI Generator：生成代码

二、在 Linux 上查看 / 调试 Swagger API（最常见）

✅ 方式 1：直接访问 Swagger UI（最简单）

如果你的后端项目已经集成 Swagger：

http://服务器IP:端口/swagger-ui.html

或：

http://服务器IP:端口/swagger

例如：

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

前提：后端已启用 Swagger（Spring Boot / FastAPI / Node.js 等）

三、在 Linux 上本地运行 Swagger UI

✅ 方式 2：用 Docker 启动 Swagger UI（推荐）

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

访问：

http://localhost:8080

适合：

• 已有 swagger.json / openapi.yaml
• 本地测试 API 文档

✅ 方式 3：直接下载 Swagger UI

wget https://github.com/swagger-api/swagger-ui/archive/refs/heads/master.zip
unzip master.zip
cd swagger-ui-master/dist
python3 -m http.server 8080

访问：

http://localhost:8080

四、在 Linux 上编写 Swagger API（Swagger Editor）

✅ 方式 4：Docker 启动 Swagger Editor

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

访问：

http://localhost:8081

你可以在浏览器里写 openapi: 3.0.0 规范。

五、在 Linux 后端项目中使用 Swagger（按语言）

✅ Java（Spring Boot）

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
</dependency>

访问：

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

✅ Python（FastAPI，最省事）

from fastapi import FastAPI
app = FastAPI()

@app.get("/items")
def read_items():
    return {"item": "hello"}

自动生成：

http://localhost:8000/docs

✅ Node.js（Express）

npm install swagger-ui-express swagger-jsdoc

六、用 Swagger 生成代码（进阶）

✅ 安装 OpenAPI Generator

brew install openapi-generator  # macOS
# 或 linux
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.6.0/openapi-generator-cli-6.6.0.jar

生成前端/后端代码：

java -jar openapi-generator-cli.jar generate \
  -i swagger.yaml \
  -g python \
  -o ./client

七、常见问题

❓ Linux 没有浏览器怎么办？

• 用 curl 测试接口
• 用 远程访问：本地浏览器访问 Linux 服务器 IP
• 用 lynx / w3m（不推荐）

❓ Swagger 和 OpenAPI 有啥区别？

✅ 现在一般说 Swagger = OpenAPI + UI

八、快速选择指南

如果你愿意，可以告诉我：

• ✅ Linux 发行版（CentOS / Ubuntu / 麒麟）
• ✅ 后端语言（Java / Python / Node）
• ✅ 是“看接口”还是“写接口”

我可以直接给你一步一步的命令。