debian swagger如何入门

下面给你一个Debian 上 Swagger 入门的实用路线，适合“刚接触 Swagger / OpenAPI”的情况。

一、先弄清楚：Swagger 是什么？

Swagger 是一套 API 描述与可视化工具，现在标准叫 OpenAPI。

常见用途：

• 用注释/配置文件描述 REST API
• 自动生成接口文档
• 提供网页版 UI 直接调试接口

核心组件：

• OpenAPI Spec（yaml/json 描述文件）
• Swagger UI（网页看文档）
• Swagger Editor（写 API 文件）
• Swagger Codegen（生成代码）

二、Debian 环境准备

1. 更新系统

sudo apt update
sudo apt upgrade -y

2. 安装基础工具

sudo apt install -y curl wget git openjdk-17-jdk

三、最快入门方式（推荐）：Swagger UI

方式一：用 Docker（最简单）

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

运行 Swagger UI：

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

浏览器访问：

http://localhost:8080

你会看到一个示例 API 文档。

方式二：直接在 Debian 上跑（不依赖 Docker）

sudo apt install -y nodejs npm

git clone https://github.com/swagger-api/swagger-ui.git
cd swagger-ui
npm install
npm run dev

访问：

http://localhost:3200

四、写你的第一个 OpenAPI 文件

新建 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 UI 中：

• 点击 Explore
• 输入 swagger.yaml 路径或 URL

五、在代码里用 Swagger（以 Python 为例）

Flask + Swagger

pip install flask flask-restx

from flask import Flask
from flask_restx import Api, Resource

app = Flask(__name__)
api = Api(app, title="示例 API")

@api.route('/hello')
class Hello(Resource):
    def get(self):
        return {"message": "Hello Swagger"}

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

访问：

http://localhost:5000/

六、学习路径建议

1. 先会用 Swagger UI
2. 学写 OpenAPI 3.0 YAML
3. 再学在项目中自动生成文档
4. 最后学 Codegen / Mock Server

七、常见坑

• Debian 旧版本 Java 太老 → 用 openjdk-17
• Swagger ≠ Spring 专用
• YAML 缩进错误最常见

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

• 你用的是 Python / Java / Go / Node
• 是想 看文档 还是 自动生成

我可以直接给你对应项目的 Swagger 示例。