Linux上Swagger API文档格式有哪些规范

Linux上Swagger API文档格式规范

一 规范版本与文件格式

• 术语澄清：业界常把基于 OpenAPI 的文档工具链称为 Swagger，实际编写遵循的是 OpenAPI Specification（OAS）。常用版本包括：OpenAPI 2.0（Swagger 2.0）、OpenAPI 3.0.x、OpenAPI 3.1.x。文档可用 JSON 或 YAML 编写，二者等价，YAML 更易读。OAS 3.1 与 JSON Schema 2020-12 对齐，表达能力更强。规范字段名区分大小写。在 Linux 环境下，这些规则与操作系统无关，适用于任何支持 OAS 的工具链与运行时。

二 文档结构与必填项

• OpenAPI 2.0 核心结构
  • 必填：swagger: “2.0”、info（至少包含 title、version）、paths。
  • 常用：host、basePath、schemes（如 http/https）、consumes、produces、definitions（数据模型）、parameters、responses、securityDefinitions、security、tags。
  • 示例要点：
    • 完整 URL 形态：:////。
    • 全局 consumes/produces 可被具体路径/操作覆盖。
• OpenAPI 3.x 核心结构
  • 必填：openapi（如 3.0.0/3.1.0）、info、paths。
  • 常用：servers（可多环境）、components（含 schemas/parameters/responses/requestBodies/headers/securitySchemes）、security、tags、externalDocs。
  • 示例要点：
    • 请求体统一在 requestBody.content..schema 中描述，支持多媒体类型。
    • 认证在 components.securitySchemes 定义，在根或操作级 security 引用。

三 数据模型与参数响应规范

• 数据类型与格式
  • 基本类型：integer、number、string、boolean；文件用 string+binary 或专用 file 类型。
  • 常见格式：int32/int64、float/double、byte（Base64）、binary、date（RFC3339 full-date）、date-time（RFC3339）、password。
  • 语义化类型：如 email、uuid 等可作为 format 使用（提示 UI 与校验）。
• 参数规则
  • 位置（in）：path、query、header、cookie；path 参数必须 required: true。
  • 请求体：在 OAS 2.0 使用 body 参数（每个操作最多一个）；在 OAS 3.x 使用 requestBody（可多 content-type）。
  • 约束：可用 required、minimum、maximum、enum、pattern 等约束；数组需定义 items。
• 响应规范
  • 每个操作必须定义至少一个响应（如 200），并给出 description 与 schema/content。
  • 可为不同状态码（如 4xx/5xx）分别定义响应体结构；建议提供 examples。
• 复用与引用
  • 模型在 definitions（OAS 2.0） 或 components.schemas（OAS 3.x） 定义，通过 $ref 复用；请求参数、响应、头部等也可抽取到 components 复用。

四 安全与可维护性规范

• 认证与授权
  • 支持 API Key（header/query/cookie）、HTTP Basic、OAuth2（多种 flow） 等；在 securityDefinitions 声明，在 security 应用（全局或操作级），可组合 OR/AND 要求。
• 服务器与环境
  • 使用 servers 区分 开发/测试/生产 环境 URL，便于切换与文档测试。
• 可维护性与工具链
  • 使用 tags 对接口分组；提供 externalDocs 指向设计说明/变更记录。
  • 采用 YAML 编写、配合 Swagger Editor 实时校验与预览；通过 Swagger UI/Redoc 渲染交互式文档；用 OpenAPI Generator/Swagger Codegen 生成客户端/服务端桩代码，保持文档与实现一致。

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