linux swagger怎么使用

在 Linux 下使用 Swagger，通常是指 Swagger/OpenAPI 用于 API 文档的编写、查看和测试。下面按最常见场景给你一个清晰、实用的说明。

一、Swagger 是什么？

Swagger 是一套 RESTful API 文档工具，现在主流标准是 OpenAPI。

常见用途：

自动生成 API 文档
在浏览器中直接测试接口
前后端基于文档对接

二、Linux 下常见的 3 种使用方式

✅ 方式一：Swagger UI（最常用）

适合：查看和调试 API

1️⃣ 下载 Swagger UI

wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v5.17.14.zip
unzip v5.17.14.zip
cd swagger-ui-5.17.14/dist

2️⃣ 启动一个简单的 HTTP 服务

python3 -m http.server 8080

3️⃣ 浏览器访问

http://服务器IP:8080

4️⃣ 加载你的 API 文档

修改 swagger-initializer.js：

url: "http://你的IP:端口/v3/api-docs",

或者直接在页面顶部输入：

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

✅ 适合 Java / Spring Boot / Go / Node 等后端项目

✅ 方式二：Spring Boot + Swagger（最常见）

适合 Java 后端

1️⃣ 添加依赖（Springfox 已过时，推荐 springdoc）

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

2️⃣ 启动项目

访问：

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

或：

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

✅ 无需额外安装，Linux 服务器直接访问即可

✅ 方式三：命令行使用 Swagger（OpenAPI CLI）

适合生成、校验 API 文档

1️⃣ 安装 Swagger CLI

npm install -g @apidevtools/swagger-cli

（如果没有 npm）

sudo apt install nodejs npm

2️⃣ 校验 OpenAPI 文件

swagger-cli validate openapi.yaml

3️⃣ 合并多个 API 文件

swagger-cli bundle openapi.yaml -o bundled.yaml

三、常见 openapi.yaml 示例

openapi: 3.0.3
info:
  title: Linux API Demo
  version: 1.0.0
paths:
  /hello:
    get:
      summary: Hello接口
      responses:
        '200':
          description: OK

四、常见问题

❓ Linux 没有浏览器怎么办？

✅ 使用：

本地浏览器访问 服务器 IP + 端口
或者用 curl + Swagger UI 部署

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

❓ Swagger 和 OpenAPI 有什么区别？

名称	说明
Swagger	老品牌
OpenAPI	官方标准
Swagger UI	可视化工具

✅ 现在一般用 OpenAPI 3.x + Swagger UI

五、总结（快速选择）

你是…	推荐方式
Java 后端	Spring Boot + springdoc
只想看接口	Swagger UI
写 API 文档	openapi.yaml
自动生成代码	Swagger Codegen

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

✅ 你是 Java / Go / Python / Node 哪个？
✅ 是 已有项目 还是 从零开始？
✅ 想 看文档 还是 自动生成接口？

我可以直接给你 完整可运行的示例。