3. API接口文档规范：OpenAPI/Swagger规范介绍、文档结构、请求/响应模型定义

3.1 OpenAPI/Swagger 规范概述

OpenAPI 规范（原 Swagger 规范）是业界标准的 RESTful API 接口描述语言，它定义了一套与编程语言无关的接口契约。通过 OpenAPI 文档，开发者可以清晰地了解 API 的端点、请求参数、响应结构以及认证方式，从而实现服务端与客户端之间的解耦与自动化工具链支持。

3.2 文档结构：从根对象到路径

一个标准的 OpenAPI 文档由顶层对象开始，逐层展开。以下是最小化但完整的文档骨架：

openapi: "3.0.3"
info:
  title: 日志检索准入门禁自助服务 API
  description: 提供门禁权限的申请、审批、日志查询接口
  version: "1.0.0"
  contact:
    name: API 支持团队
    email: api-support@example.com
servers:
  - url: https://api.example.com/v1
    description: 生产环境
paths:
  /access-requests:
    post:
      summary: 提交门禁权限申请
      operationId: createAccessRequest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessRequest'
      responses:
        '201':
          description: 申请创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessRequestResponse'
components:
  schemas:
    AccessRequest:
      type: object
      properties:
        userId:
          type: string
        areaCode:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
      required:
        - userId
        - areaCode
        - startTime
        - endTime
    AccessRequestResponse:
      type: object
      properties:
        requestId:
          type: string
        status:
          type: string
          enum: [pending, approved, rejected]
        createdAt:
          type: string
          format: date-time

3.3 请求模型定义：参数与请求体

在 OpenAPI 中，请求参数分为三类：路径参数、查询参数、请求头参数，以及请求体（requestBody）。以下表格对比了它们的定义位置与使用场景：

3.4 响应模型定义：状态码与内容类型

每个 API 端点可以定义多个响应状态码，每个状态码下可指定返回的内容类型和对应的 Schema。推荐的做法是：

• 2xx 成功响应：返回业务数据实体。
• 4xx 客户端错误：返回统一的错误结构，包含错误码、消息和请求追踪 ID。
• 5xx 服务端错误：返回最小化错误信息，避免泄露内部细节。

responses:
  '200':
    description: 查询成功
    content:
      application/json:
        schema:
          type: object
          properties:
            code:
              type: integer
              example: 0
            message:
              type: string
              example: "success"
            data:
              type: array
              items:
                $ref: '#/components/schemas/AccessLog'
  '400':
    description: 请求参数错误
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'
  '401':
    description: 未授权
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'

3.5 模型复用与 $ref 引用

当多个端点共享相同的数据结构时，应使用 $ref 引用 components/schemas 中定义的模型。这不仅能减少文档冗余，还能确保一致性。

components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
          description: 业务错误码
        message:
          type: string
          description: 人类可读的错误描述
        requestId:
          type: string
          description: 请求追踪 ID，用于日志关联
      required:
        - code
        - message
    PaginatedResponse:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
        total:
          type: integer
        page:
          type: integer
        size:
          type: integer

3.6 文档工具链与自动化

基于 OpenAPI 规范的文档，可以无缝接入以下工具链：