linux swagger文档怎么写

在 Linux 环境下写 Swagger 文档，本质上和在 Windows / macOS 上一样，只是工具运行方式、目录结构、命令是 Linux 风格。下面按「最常用场景」给你一个完整说明。

一、Swagger 文档常见写法（Linux 通用）

Swagger 文档主要有 两种写法：

1. OpenAPI / Swagger YAML 或 JSON 文件
2. 代码里写注解，自动生成 Swagger（推荐）

二、方式一：直接写 Swagger YAML（最简单）

1️⃣ 创建文件

mkdir -p ~/swagger
cd ~/swagger
vim swagger.yaml

2️⃣ 示例 Swagger YAML

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

3️⃣ 本地预览（Linux）

docker run -p 8080:8080 \
  -v $PWD/swagger.yaml:/swagger.yaml \
  swaggerapi/swagger-ui

浏览器访问：

http://localhost:8080

三、方式二：代码中写 Swagger（最常见）

✅ Java（Spring Boot）

# Linux 下运行
./mvnw spring-boot:run

@Operation(summary = "获取用户")
@GetMapping("/users")
public List<User> getUsers() {
    return userService.list();
}

依赖：

<dependency>
  <groupId>io.swagger.core.v3</groupId>
  <artifactId>swagger-annotations</artifactId>
</dependency>

访问：

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

✅ Python（FastAPI，Linux 最推荐）

pip install fastapi uvicorn

from fastapi import FastAPI

app = FastAPI()

@app.get("/users")
def get_users():
    return [{"id": 1, "name": "linux"}]

运行：

uvicorn main:app --host 0.0.0.0 --port 8000

自动文档：

http://服务器IP:8000/docs

✅ Go（swaggo）

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

// @Summary 获取用户
// @Router /users [get]

访问：

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

四、Linux 下常用工具

五、Linux 服务器部署建议

• 用 Nginx + Swagger UI
• 文档文件放 /opt/swagger/
• 用 systemd 或 docker 管理

六、你可以告诉我

我可以给你 更精确的示例，只要告诉我：

1. 用的是什么语言（Java / Python / Go / Node）
2. 是 手写 YAML 还是 代码生成
3. 是否在 Linux 服务器 上部署

我可以直接给你一套可复制的 Linux 示例。