Debian下Swagger怎么用

在 Debian 下使用 Swagger，通常取决于你是 写接口文档、生成代码，还是 在项目中集成 Swagger UI。下面按常见场景给你一个完整说明（以 Debian 11/12 为例）。

一、Swagger 相关概念先理清

二、在 Debian 下安装 Swagger（通用方式）

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

Debian 官方源里没有 swagger 包，用 Docker 最省事。

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

1️⃣ 启动 Swagger Editor

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

浏览器访问：

http://localhost:8080

2️⃣ 启动 Swagger UI

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

访问：

http://localhost:8081

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

sudo apt install -y wget unzip
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
python3 -m http.server 8080

访问：

http://localhost:8080

修改 swagger.json 路径即可加载你的接口文档。

三、编写 Swagger / OpenAPI 文档

示例 swagger.yaml：

openapi: 3.0.0
info:
  title: 示例 API
  version: 1.0.0
paths:
  /hello:
    get:
      summary: 示例接口
      responses:
        '200':
          description: 成功
          content:
            application/json:
              example:
                msg: "Hello Swagger"

在 Swagger Editor 里粘贴即可实时预览。

四、在 Debian 项目中使用 Swagger（常见语言）

✅ Java / Spring Boot（最常见）

1️⃣ 使用 springdoc-openapi（推荐）

<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️⃣ 示例 Controller

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello Swagger";
    }
}

✅ 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 Codegen（生成代码）

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

生成 Python 客户端：

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

六、常见问题

❓ Debian 能直接 apt 安装 swagger 吗？

❌ 不能，Swagger 不是系统软件，推荐 Docker 或手动部署。

❓ Swagger 和 OpenAPI 有区别吗？

✅ 现在 Swagger = OpenAPI 工具集，规范叫 OpenAPI。

七、推荐组合（Debian 服务器）

如果你能告诉我：

• ✅ 使用 什么语言 / 框架
• ✅ 是 写文档 还是 接接口
• ✅ Debian 是 本地 / 服务器 / Docker 环境

我可以给你 精确到命令级别 的方案。