Linux环境下Swagger API文档的格式规范

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 语法与规范校验，确保合并即正确。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！