linux swagger怎么用

在 Linux 环境下使用 Swagger，常见场景主要有两个：

1. 写接口文档（Swagger / OpenAPI）
2. 在 Linux 上运行 Swagger 工具（编辑、生成、查看）

下面我按“从零开始”讲，适合新手。

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

• Swagger = OpenAPI 规范
• 常用工具：
  • Swagger Editor：写 YAML/JSON 接口文档
  • Swagger UI：把文档可视化成网页
  • Swagger Codegen / OpenAPI Generator：根据文档生成代码

二、Linux 上最快使用 Swagger（推荐方式）

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

# 启动 Swagger Editor
docker run -d -p 8080:8080 swaggerapi/swagger-editor

# 启动 Swagger UI
docker run -d -p 8081:8080 swaggerapi/swagger-ui

浏览器访问：

• Swagger Editor：http://localhost:8080
• Swagger UI：http://localhost:8081

方式 2：本地安装 Swagger Editor（Node 环境）

# 安装 Node.js
sudo apt update
sudo apt install nodejs npm

# 下载 Swagger Editor
wget https://github.com/swagger-api/swagger-editor/archive/refs/heads/master.zip
unzip master.zip
cd swagger-editor-master
npm install
npm start

访问：

http://localhost:8080

三、写一个最简单的 Swagger 文档（OpenAPI 3）

swagger.yaml 示例：

openapi: 3.0.0
info:
  title: 示例 API
  version: 1.0.0
paths:
  /hello:
    get:
      summary: 打招呼
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

在 Swagger Editor 粘贴即可看到效果。

四、在代码里集成 Swagger（常见语言）

1️⃣ Java（Spring Boot）

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

访问：

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

2️⃣ Python（FastAPI ✅ 自带 Swagger）

from fastapi import FastAPI

app = FastAPI()

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

启动后访问：

http://localhost:8000/docs

3️⃣ Go（swag）

go install github.com/swaggo/swag/cmd/swag@latest
swag init

五、用 Swagger 生成代码（可选）

npm install -g @openapitools/openapi-generator-cli

openapi-generator-cli generate \
  -i swagger.yaml \
  -g java \
  -o ./out

六、常见问题

❓ Linux 没有界面怎么办？

• 用 Docker
• 或把文档写好，在本地 Windows/Mac 看 UI

❓ 端口被占用？

-p 9090:8080

七、总结一句话

Linux 上用 Swagger = Docker 跑 Editor/UI + 写 OpenAPI YAML

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

• 你用的语言（Java / Python / Go？）
• 是想 写文档 还是 接项目

我可以直接给你一套可跑的配置。