如何在OpenAPI 3.0规范中合理维护API变更日志？

OpenAPI 3.0 规范本身并没有定义专门用于维护版本变更日志的标准字段，但你可以通过以下几种纯JSON文件友好的方式来管理变更记录，完全无需依赖付费工具：

1. 使用自定义扩展字段 x-changelog #

OpenAPI 允许添加以 x- 开头的自定义扩展字段，你可以直接在 info 节点下新增 x-changelog，用结构化或纯文本格式存储日志：

结构化示例（方便工具解析） #

"info": {
  "version": "0.1.2",
  "title": "个人信息API",
  "x-changelog": [
    {
      "version": "0.1.2",
      "date": "2022/11/26",
      "changes": [
        "other changes..."
      ]
    },
    {
      "version": "0.1.1",
      "date": "2022/11/25",
      "changes": [
        "added \"gender\" attribute to response of \"/getPersonalDetails\"",
        "changed \"record_dt\" format of \"/getPersonalDetails\" from \"YYYY-MM-DD\" to \"YYYY-MM-DD hh:mm:ss\""
      ]
    }
  ]
}

纯文本示例（适合人工快速阅读） #

"info": {
  "version": "0.1.2",
  "title": "个人信息API",
  "x-changelog": "V0.1.1 - 2022/11/25\n- added \"gender\" attribute to response of \"/getPersonalDetails\"\n- changed \"record_dt\" format of \"/getPersonalDetails\" from \"YYYY-MM-DD\" to \"YYYY-MM-DD hh:mm:ss\"\n\nV0.1.2 - 2022/11/26\n- other changes..."
}

这种方式的优势是变更日志和API规范同文件，共享方便，且完全符合OpenAPI规范。

2. 单独维护变更日志JSON文件 #

如果担心主API规范文件过于臃肿，可以单独创建一个如 changelog.json 的文件，和主OpenAPI文件一起分发：

{
  "api-spec-version": "0.1.2",
  "entries": [
    {
      "version": "0.1.2",
      "date": "2022/11/26",
      "changes": ["other changes..."]
    },
    {
      "version": "0.1.1",
      "date": "2022/11/25",
      "changes": [
        "added \"gender\" attribute to response of \"/getPersonalDetails\"",
        "changed \"record_dt\" format of \"/getPersonalDetails\" from \"YYYY-MM-DD\" to \"YYYY-MM-DD hh:mm:ss\""
      ]
    }
  ]
}

这种方式适合版本迭代频繁、变更记录较多的场景，能保持主规范文件的简洁性。

3. 优化 info.description 的排版 #

如果坚持使用现有字段，可以在 info.description 中用Markdown格式分隔正常API描述和变更日志，大部分OpenAPI渲染工具（如Swagger UI）都能正确解析：

"info": {
  "description": "个人信息查询API，用于获取用户的个人详细信息。\n\n## 版本变更日志\n\n### V0.1.1 - 2022/11/25\n- added \"gender\" attribute to response of \"/getPersonalDetails\"\n- changed \"record_dt\" format of \"/getPersonalDetails\" from \"YYYY-MM-DD\" to \"YYYY-MM-DD hh:mm:ss\"\n\n### V0.1.2 - 2022/11/26\n- other changes...",
  "version": "0.1.2"
}

以上几种方案都能满足你用独立JSON文件共享、清晰管理变更记录的需求，其中自定义扩展字段 x-changelog 是最贴合OpenAPI规范的首选方式。

内容的提问来源于stack exchange，提问作者gzg