4. 接口文档规范：Swagger/OpenAPI、YApi 工具的编写要点

说实话，我在审计项目里见过太多接口联调翻车的案例。一查原因，多半是接口文档写得像天书——要么字段漏了，要么枚举值不对，甚至根本就没文档。你想想看，审计接口集成如果连个靠谱的文档都没有，那后面测试、认证、回溯全得靠猜。

所以我个人习惯，在所有审计集成项目里，先把接口文档规范定死。文档写清楚了，审计的效率至少提升一倍。今天咱们就聊聊 Swagger/OpenAPI 和 YApi 这两个主流工具，怎么写出让审计师和开发都满意的接口文档。

4.1 为什么接口文档规范对审计至关重要

审计接口集成的核心目标是可追溯、可验证。没有规范的文档，你拿什么去跟审计师证明「这个字段是必填的」「那个值只允许0和1」？

• 一致性：Swagger 定义的标准结构，确保接口描述、参数、响应用同一套模板，不会出现你写你的、我写我的。
• 自动化校验：审计工具可以直接读取 OpenAPI 规范，自动比对报文是否合规。我在一个金融项目里就用这招，省了整整两周的人工对账。
• 沟通语言：审计师、产品、开发、测试，大家对着同一个规范的文档讨论，错误率直线下降。

4.2 Swagger/OpenAPI 规范编写要点

OpenAPI 3.0 是目前的主流，Swagger 工具集支持得很好。写规范文档，我建议抓住这几个核心点。

4.2.1 路径与参数定义

每个接口的路径要清晰表达资源类型。比如审计日志查询接口：

paths:
  /audit/logs:
    get:
      summary: 按条件查询审计日志
      parameters:
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: eventType
          in: query
          required: false
          schema:
            type: string
            enum: [LOGIN, LOGOUT, DATA_CHANGE, EXPORT]

注意，枚举值一定要写全。我在一个项目中遇到审计师追问「为什么会有其他值进来」，最后发现接口文档里只写了三个，实际却传了第四个。自那以后，我要求所有枚举字段加 nullable: false 并注明默认值。

4.2.2 请求与响应体模型

用 components/schemas 定义可复用的 DTO，避免每处重复写相同结构。审计场景下，常用的「分页响应」模型可以抽出来：

components:
  schemas:
    PageResult:
      type: object
      properties:
        total:
          type: integer
          description: 总条数
        page:
          type: integer
          description: 当前页码
        size:
          type: integer
          description: 每页大小
        records:
          type: array
          items:
            $ref: '#/components/schemas/AuditLog'

这样写，所有分页接口都能引用同一个模型。审计师查起来也一目了然。

4.2.3 错误响应标准化

审计集成中，错误码必须统一。我习惯定义一个 ErrorResponse 模型：

    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          example: AUDIT_1001
        message:
          type: string
          example: "开始日期不能晚于结束日期"
        timestamp:
          type: string
          format: date-time

然后在每个接口的 responses 里引用它。这样审计系统可以根据 code 字段自动分类异常，不用去解析乱七八糟的返回体。

4.3 YApi 工具的使用技巧

YApi 是国内很多团队用的接口管理平台，开源、支持 Swagger 导入。我在好几个审计项目里都用它做文档协作。

4.3.1 项目管理与分组

按审计模块分目录：比如「用户认证」「日志查询」「数据导出」「配置管理」。每个分组下再细化接口。我在一个项目中看到有人把所有接口扔到一个大文件夹里，审计师找接口找了半小时……

建议：创建项目时，开启「Swagger 数据同步」，这样后端改完 Swagger 注解，YApi 自动更新文档，永远不滞后。

4.3.2 Mock 功能妙用

审计接口集成，经常需要测试异常场景。YApi 的 Mock 服务可以根据接口的 schema 自动生成随机数据。但我遇到过 Mock 数据格式与生产不一致的情况。所以我建议手动指定 Mock 规则，尤其是枚举字段和日期格式。

// 在 YApi 接口的高级设置中，可以为参数添加 mock 脚本
// 例如：让 status 字段只在 0,1,2 中随机
mock:
  status: '@pick(["0","1","2"])'

这样做，前端和测试在审计联调时能提前暴露问题，不用等到正式环境再手忙脚乱。

4.3.3 文档版本与变更记录

审计要求版本可追溯。YApi 支持每个接口的修改历史，但我个人习惯在项目开头就约定：每次变更必须填写「变更说明」，最好关联到 Jira 或禅道工单。这样审计师查起来，能清楚知道每次修改的原因和时间。

4.4 核心关系图：接口文档规范与审计集成流程

下面这张图梳理了接口文档规范在整个审计接口集成中的位置，以及各工具之间的关系。

4.5 各维度对比：Swagger vs YApi vs 手写文档

我整理了一张对比表，方便你在项目初期选择主工具。注意，这些工具不是互斥的，可以配合使用。

维度	Swagger/OpenAPI	YApi	手写文档（Word/Excel）
规范性	强，有标准 Schema	中，依赖导入质量	弱，风格因人而异
自动化支持	好，可生成代码、测试	好，Mock+测试集	差，需手动维护
协作协作	需配合 Git 或 Swagger Hub	内置团队协作、评论	邮件传来传去，容易丢
审计追溯	版本控制（Git 或文件）	有历史版本，但需手动记录变更原因	很难追溯
推荐场景	源头标准定义、微服务、审计对接	团队协作、前后端联调、快速 Mock	仅用于概念性文档或非正式项目

4.6 避坑指南（我踩过的坑）

• 坑一：Swagger 注解和文档不同步。 我曾经发现后端改了接口参数名，但注解里的 @ApiModelProperty 没更新，导致生成的 Swagger 文档字段名还是旧的。测试拿旧文档去调审计接口，死活不通。后来我强制要求：每个接口变更必须同时在代码和文档里改，并加入 CI 检查 —— 如果文档和代码不一致，构建直接失败。
• 坑二：YApi 上的接口限流忘记配置。 审计系统批量查询时，瞬间请求量很大。YApi 的 Mock 默认不限流，但真实后端接口限流了，导致 Mock 测试通过，生产却报 429。解决方案：在 YApi 项目设置里开启「请求频率限制」，并配置与生产一致的值。
• 坑三：枚举值未在文档中列出。 审计数据中有个 status 字段，文档只写了「0-正常，1-异常」，结果实际还有 2-待审核、3-已删除。审计师发现数据不符合文档说明，质疑系统稳定性。所以，务必在 OpenAPI 中把 enum 写全，哪怕有些值暂时不用也要写上，作为预留。