如何在Azure API Management开发者门户友好展示OpenAPI请求体Schema？

我之前帮客户处理过类似的场景，针对你遇到的Azure APIM开发者门户里JSON-API请求体Schema展示不友好的问题，有几个实用的方案可以试试：

1. 从源头上优化OpenAPI 2.0定义（最推荐） #

APIM开发者门户的文档展示完全依赖你上传的OpenAPI规范，所以先把你的Swagger定义做针对性增强，就能直接改善展示效果：

• 给JSON-API的核心结构（data、attributes、relationships等）添加清晰的description字段，让门户渲染时自动带上说明文字
• 用OpenAPI 2.0支持的自定义扩展x-example，给嵌套结构添加贴合JSON-API规范的完整示例，补充默认sample的细节
• 明确标记JSON-API要求的必填字段（比如type、data），并给每个属性添加具体的业务说明

举个优化后的Schema片段示例：

"definitions": {
  "PostResource": {
    "type": "object",
    "description": "符合JSON-API v1.0规范的文章资源对象",
    "required": ["data"],
    "properties": {
      "data": {
        "type": "object",
        "description": "JSON-API标准顶级数据容器，承载资源核心信息",
        "required": ["type", "attributes"],
        "properties": {
          "type": {
            "type": "string",
            "description": "资源类型标识，全局唯一，固定为'posts'",
            "example": "posts"
          },
          "id": {
            "type": "string",
            "description": "资源唯一ID（创建请求可选，更新/删除请求必填）",
            "example": "post-123"
          },
          "attributes": {
            "type": "object",
            "description": "文章的业务属性集合",
            "properties": {
              "title": {
                "type": "string",
                "description": "文章标题，最长100字符",
                "example": "Getting Started with JSON-API"
              },
              "publish_date": {
                "type": "string",
                "format": "date-time",
                "description": "文章发布时间，ISO 8601格式",
                "example": "2024-05-20T14:30:00Z"
              }
            }
          }
        },
        "x-example": {
          "data": {
            "type": "posts",
            "attributes": {
              "title": "Getting Started with JSON-API",
              "publish_date": "2024-05-20T14:30:00Z"
            }
          }
        }
      }
    }
  }
}

2. 自定义开发者门户的请求体渲染模板 #

如果优化OpenAPI定义后还是达不到预期，你可以直接修改APIM开发者门户的模板逻辑，针对JSON-API做特殊渲染：

• 进入APIM实例的开发者门户，点击右上角的Manage按钮切换到管理模式
• 导航到Templates菜单，找到Operation Details下的Request Body相关模板（或者全局的Schema渲染模板）
• 修改模板的HTML、CSS和JS代码：
  • 增加判断逻辑，识别JSON-API格式的Schema（比如检测是否包含顶级data属性）
  • 把嵌套的Schema结构渲染成更直观的层级视图，添加折叠/展开功能
  • 将属性的description和example直接展示在字段旁，替代默认的悬浮提示

这种方式灵活性最高，但需要你有一定的前端开发能力，修改后记得做好备份，避免模板升级时丢失自定义内容。

3. 考虑升级到OpenAPI 3.x（长期方案） #

OpenAPI 2.0的Schema描述能力有限，如果你有条件，建议把API规范升级到OpenAPI 3.x版本：

• OpenAPI 3.x支持更丰富的Schema表达式（比如oneOf、anyOf的可视化展示更清晰）
• APIM对OpenAPI 3.x的默认渲染效果更好，能自动识别更多JSON-API的结构特征
• 3.x的example和examples字段支持多示例展示，更贴合JSON-API的复杂场景

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