debian swagger怎么写文档

在 Debian 上写 Swagger（OpenAPI）文档，通常有三种常见方式：

1. 手写 OpenAPI / Swagger YAML 或 JSON
2. 代码注解自动生成（Spring / Flask / Go 等）
3. 使用 Swagger Editor / Swagger UI 在 Debian 上查看和调试

下面按“从零开始”的思路说明。

一、在 Debian 上安装 Swagger 工具

1. 安装 Swagger Editor（推荐）

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

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

二、手写 Swagger 文档（OpenAPI 3）

示例：swagger.yaml

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
  description: Debian 上的 Swagger 示例
servers:
  - url: http://localhost:8080
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
  /users/{id}:
    get:
      summary: 根据用户ID获取用户
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

保存为 swagger.yaml，在 Swagger Editor 中打开即可。

三、代码自动生成 Swagger（常见语言）

1. Python（FastAPI，最简单）

pip install fastapi uvicorn

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    id: int
    name: str

@app.get("/users", response_model=list[User])
def get_users():
    return [User(id=1, name="Tom")]

启动：

uvicorn main:app --reload

访问：

http://localhost:8000/docs

2. Java（Spring Boot）

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

访问：

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

3. Go（swag）

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

四、在 Debian 上托管 Swagger 文档

sudo apt install nginx

server {
    listen 80;
    root /var/www/swagger;
    index index.html;
}

把 Swagger UI 的 dist 目录放进去即可。

五、总结

✅ Debian 写 Swagger 文档流程：

1. 写 openapi.yaml
2. Swagger Editor 编辑
3. Swagger UI 展示
4. 或用框架自动生成

如果你告诉我：

• 用 什么语言
• REST 还是 gRPC
• 是否要 自动生成

我可以直接给你一套完整示例。