Linux环境下 Swagger API 文档格式规范
一 规范版本与文件格式
- 术语澄清：业界所称的 Swagger 规范在 2015 年捐赠给 OpenAPI Initiative 后演进为 OpenAPI Specification（OAS）；工程中常把基于 OAS 的文档与工具链统称为 Swagger。OAS 文档可用 JSON 或 YAML 编写，字段名区分大小写，支持通过 $ref 拆分到多文件维护。推荐 YAML 以提升可读性，且便于与 JSON 互转。根对象关键字：OAS 3.x 使用 openapi: 3.x.x，Swagger 2.0 使用 swagger: “2.0”。为跨版本工具兼容，建议在项目中固定一个主版本并统一使用。
二 文档结构与必填项
- OAS 3.x 核心结构（必备与常用）
- 必备：openapi、info（含 title、version）、paths
- 常用：servers（多环境地址）、components（集中定义 schemas、parameters、responses、securitySchemes）、security（全局安全要求）
- Swagger 2.0 核心结构（必备与常用）
- 必备：swagger: “2.0”、info、paths
- 常用：host、basePath、schemes、consumes、produces、definitions、parameters、responses、securityDefinitions、security
- 语义要点
- info.license 建议包含 name 与可选 url；paths 下每个 operation 必须定义 responses；parameters 需声明 in（如 path|query|header）与 required；requestBody 在 3.x 中使用，2.0 使用 body 参数；security 支持按操作覆盖全局策略。
三 数据模型与参数响应规范
- 数据类型与格式
- 基础类型：integer（format: int32|int64）、number（float|double）、string（含 date、date-time、byte、binary、password 等）、boolean
- 模型定义：在 components.schemas（3.x）或 definitions（2.0）中以 type/format/properties/required 描述；可用 $ref 复用
- 参数规则
- path 参数必须声明 required: true；query 参数可声明 style 与 explode；header 参数常用 schema 限定类型
- 请求体与响应体
- 3.x：在 requestBody.content..schema 定义；可为不同媒体类型提供不同 schema/examples
- 2.0：在 parameters 中使用 in: body 并提供 schema
- 常用响应
- 至少定义 200（成功）与常见错误码（如 400/401/404/500）；每个响应需有 description，必要时提供 examples 或 content 结构。
四 安全与可复用组件规范
- 安全方案（3.x 推荐在 components.securitySchemes 定义）
- apiKey（在 header 或 query）、http（如 basic）、oauth2（支持 implicit|password|clientCredentials|authorizationCode 等流程与 scopes）
- 全局与局部生效
- 在根级 security 声明全局策略；在具体 operation 下可覆盖（如仅管理员 scope 或完全免认证）
- 组合逻辑
- 数组项表示“或”（满足其一即可），同一数组内多对象表示“与”（需同时满足），可组合出复杂安全需求
- 可复用性
- 将通用 schemas/parameters/responses/securitySchemes 放入 components，通过 $ref: ‘#/components/…’ 引用，避免重复与漂移。
五 Linux 下的书写与验证流程
- 本地编辑与校验
- 使用 Swagger Editor 进行语法高亮、即时校验与预览；将规范保存为 openapi.yaml 或 swagger.yaml，必要时转换为 JSON
- 快速启动编辑器（示例）
- 安装 Node.js 后，下载并启动 Swagger Editor：
- npm 安装 http-server
- 下载解压 swagger-editor 发行包
- 在解压目录执行：http-server -p 8080
- 浏览器访问：http://<服务器IP>:8080
- 集成与展示
- 使用 Swagger UI 或 ReDoc 渲染交互式文档；在 CI 中加入 YAML/JSON 语法与规范校验，确保合并即正确。