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

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

一 规范总览与版本选择

• 在 Linux 环境中，Swagger 已演进为 OpenAPI Specification（OAS），文档以 YAML 或 JSON 编写，二者语法等价、工具普遍支持，建议优先使用 YAML 以提升可读性与可维护性。OAS 主流版本为 2.0 与 3.0+，新项目推荐 3.0+，其结构更清晰、复用能力更强（如 components）。
• 版本差异要点（便于团队统一规范）：
  • OAS 2.0 根字段为 swagger: “2.0”，使用 host、basePath、schemes、consumes、produces 等；数据模型在 definitions。
  • OAS 3.0+ 根字段为 openapi: 3.0.0，使用 servers 统一管理服务地址；请求/响应体通过 requestBody/content 与 responses/content 描述；数据模型集中在 components/schemas。
• 在 Linux 上可通过 Docker 快速起 Swagger Editor 进行本地编写与实时校验，确保遵循上述结构与字段规范。

二 文件结构与必填字段规范

• 推荐的 OAS 3.0+ 最小规范骨架（YAML）：

openapi: 3.0.0
info:
  title: 示例 API
  version: 1.0.0
  description: API 文档规范示例
servers:
  - url: http://localhost:3000/api/v1
    description: 本地开发环境
paths:
  /users:
    get:
      summary: 获取用户列表
      description: 返回用户基本信息
      operationId: getUsers
      tags:
        - 用户
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
          description: 页码
          required: false
      responses:
        '200':
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: 张三
        email:
          type: string
          format: email
          example: user@example.com
  responses:
    BadRequest:
      description: 请求参数错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          example: 400
        message:
          type: string
          example: 参数校验失败

• 关键规范点：
  • 使用 servers 而非 OAS 2.0 的 host/basePath/schemes；请求/响应体统一放在 content 下，并按媒体类型（如 application/json）声明 schema。
  • 为可复用对象统一放在 components（如 schemas、responses、parameters、examples），通过 $ref 引用，避免重复定义。
  • 每个 operation 建议提供 operationId（利于代码生成与文档追踪）与 tags（便于分组展示）。

三 命名与语义规范

• 文件与目录
  • 统一命名为 openapi.yaml / openapi.json 或按业务域分片（如 user-api.yaml、order-api.yaml）；与代码同仓管理，纳入 VCS。
• 字段与语义
  • 路径使用名词复数、小写、连字符或下划线风格（如 /user-profiles）；避免在路径中嵌入动词。
  • 统一 HTTP 状态码 语义：如 200 成功、201 创建成功、400 请求错误、401 未认证、403 未授权、404 资源不存在、500 服务错误；错误响应使用统一的 Error 模型。
  • 统一 Content-Type：以 application/json 为主；文件上传使用 multipart/form-data 并在 schema 中正确声明。
  • 统一 版本策略：API 版本放在 info.version；避免在路径中重复编码版本（由网关或服务路由处理）。
• 可维护性
  • 使用 tags 对接口分组（如“用户”“订单”“支付”），并在 UI 中保持分组顺序一致。
  • 为每个 operation 提供 summary/description，对复杂参数或业务规则补充 example 与 externalDocs。

四 验证与本地预览

• 本地编辑与校验
  • 使用 Swagger Editor（Docker 方式）进行语法与规范校验：
    • 启动命令：docker run -d -p 8080:8080 swaggerapi/swagger-editor
    • 访问 http://<服务器IP>:8080，导入规范文件即可实时校验与预览。
• 在应用中预览
  • 使用 Swagger UI 渲染交互式文档：
    • Docker 方式：docker run -d -p 8081:8080 -e SWAGGER_FILE=/app/openapi.yaml -v /path/to/openapi.yaml:/app/openapi.yaml swaggerapi/swagger-ui
    • 访问 http://<服务器IP>:8081 查看文档。
• 持续集成校验
  • 在 CI 中加入规范校验步骤（如通过容器运行校验工具或编辑器校验命令），阻止不合规规范合入主分支。

五 与常见框架的集成与输出规范

• Spring Boot
  • 新项目优先使用 springdoc-openapi（适配 OAS 3.0+）：
    • Maven 依赖：

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

    • 常用配置（application.properties）：
      • springdoc.api-docs.path=/api-docs
      • springdoc.swagger-ui.path=/swagger-ui
    • 访问 http://:8080/swagger-ui 查看自动生成文档。
• 传统项目使用 Springfox（OAS 2.0）
  • 依赖示例：

    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.9.2</version>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.9.2</artifactId>
    </dependency>
    

  • 注意：Springfox 对 OAS 3.0+ 支持有限，若需 3.0+ 建议迁移至 springdoc。