调用Jira Cloud REST API传ADF表格更新Issue描述报错咨询

这个报错和你提交的ADF表格结构正确性无关，是接口版本和请求配置不匹配导致的，两个核心触发原因和对应修复方式如下：

• 根因1：Jira Cloud REST API v2 版本的description字段做了强类型校验，仅接受字符串类型输入，完全不支持传入ADF结构化对象。不管你的ADF写的多标准，只要走v2接口传对象，第一步类型校验就会直接抛这个错，根本不会进入ADF格式校验环节。
• 根因2：如果已经切换到v3接口还是报这个错，基本是请求头没配对，服务端没有按ADF格式解析载荷，fallback到了v2的校验逻辑。

修复方式 #

根据你用的API版本选对应方案即可：

方案1：使用v3接口（原生支持ADF，推荐） #

1. 将请求端点从/rest/api/2/issue/{issueIdOrKey}替换为/rest/api/3/issue/{issueIdOrKey}
2. 确保请求头携带以下配置：

   Content-Type: application/json
   Accept: application/json
   X-Atlassian-Token: no-check
   

3. 你原来写的ADF结构不需要做任何调整，直接放在fields.description字段提交即可正常渲染表格。

方案2：保留v2接口使用 #

如果不想切换API版本，就不能传ADF对象，需要把富文本内容转成Jira Wiki标记字符串再传给description字段。你示例里的两列表格对应的Wiki标记如下：

|| Row one, cell one || Row one, cell two ||

直接把这段字符串作为description的值提交即可，不会触发类型错误。

常见踩坑点 #

• 用第三方封装的Jira JS请求库时，先检查库默认绑定的API版本，不少老版本客户端默认锁死v2接口，手动传ADF对象必然触发这个报错。
• 不要尝试在v2接口里给ADF套JSON.stringify转字符串提交，v2接口不会自动解析字符串化的ADF，会把整段JSON代码当纯文本展示在描述里。

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