如何写linux swagger文档

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

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

下面分别说明，并给出 Linux 下的实际操作示例。

一、手写 Swagger / OpenAPI 文档（最通用）

1. 选择格式

YAML（推荐，可读性好）
JSON

2. 示例（OpenAPI 3.0，YAML）

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
  description: Linux 环境下的用户管理接口
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

保存为：

vim swagger.yaml

二、在 Linux 中使用 Swagger Editor

1. 使用 Docker（最简单）

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

浏览器访问：

http://localhost:8080

左边写 YAML
右边实时预览

三、通过代码自动生成 Swagger 文档（常见语言）

1. Java（Spring Boot）

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping
    @Operation(summary = "获取用户列表")
    public List<User> getUsers() {
        return List.of();
    }
}

依赖（Maven）：

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

访问：

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

2. Go（swaggo）

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

代码中写注解：

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

生成：

docs/docs.swagger.json

3. Python（FastAPI）

from fastapi import FastAPI

app = FastAPI()

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

自动生成：

http://localhost:8000/docs

四、使用 Swagger CLI 校验文档

npm install -g @apidevtools/swagger-cli
swagger-cli validate swagger.yaml

五、Linux 下推荐工作流

✅ 小型项目
→ 手写 YAML + Swagger Editor

✅ 中大型项目
→ 代码注解 + 自动生成

✅ CI/CD
→ swagger-cli 校验 + 自动部署文档

如果你能告诉我：

使用什么语言（Java / Go / Python / C++）
是否已有项目
是否用于前端联调或接口网关

我可以给你更具体的 Swagger 模板和示例。