怎么写linux swagger文档

在 Linux 环境下编写 Swagger 文档（通常指 OpenAPI 文档），一般有三种常见方式：

1. 手写 OpenAPI YAML/JSON 文件
2. 在代码中通过注解自动生成（如 Spring Boot、Go、Python）
3. 使用 Swagger Editor / CLI 工具辅助编写

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

一、准备 Linux 环境

1. 安装基础工具

# 编辑文件
sudo apt install -y vim yaml-mode

# 可选：Node.js（用于 Swagger CLI / Editor）
sudo apt install -y nodejs npm

2. 安装 Swagger 工具（可选）

npm install -g swagger-cli

校验：

swagger-cli --version

二、手写 Swagger（OpenAPI）文档

1. 创建文档文件

mkdir swagger-demo
cd swagger-demo
vim swagger.yaml

2. 示例 OpenAPI 3 文档

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0
  description: Linux 下编写的 Swagger 文档示例

servers:
  - url: http://localhost:8080

paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

  /users/{id}:
    get:
      summary: 根据 ID 获取用户
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功

三、校验 Swagger 文档

swagger-cli validate swagger.yaml

输出：

swagger.yaml is valid

四、在 Linux 上查看 / 使用 Swagger

方式 1：Swagger Editor（本地）

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

浏览器访问：

http://localhost:8081

方式 2：Swagger UI

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

访问：

http://localhost:8082

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

Spring Boot（Java）

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

依赖：

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

访问：

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

Python（FastAPI）

from fastapi import FastAPI

app = FastAPI()

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

自动生成：

http://localhost:8000/docs

六、推荐工作流（Linux 实战）

1. 用 vim 写 swagger.yaml
2. swagger-cli validate 校验
3. Docker 启动 Swagger UI
4. 前端 / 测试直接看文档
5. 后端按文档实现接口

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

• 用的什么语言（Java / Go / Python / Node）
• 想要 手写 还是 自动生成
• 是否需要 鉴权（JWT / OAuth）

我可以直接给你一份可运行的完整示例。