如何在Jira创建工单REST API中正确使用Atlassian Document Format

开发者阿泽

2026-10-14

问题原因

"Operation value must be a string"报错出现的核心原因有两个：
你使用的Jira API版本不支持Atlassian Document Format (ADF)结构的description格式
你提交的description结构存在语法错误，或字段位置错误

解决方案

方案1：使用v2版本API（适用所有Jira部署类型，仅支持纯文本描述）

Jira v2版本的API默认要求description为字符串类型，直接传入文本内容即可，正确传参示例：

{
    "fields": {
        "project": {
            "key": "你的项目key"
        },
        "summary": "工单标题",
        "description": "直接填写工单描述的纯文本内容",
        "issuetype": {
            "name": "任务"
        }
        // 其余自定义字段等参数
    }
}

方案2：使用v3版本API（适用Jira Cloud，支持富文本描述）

如果需要使用富文本格式的描述，需要切换到Jira Cloud v3版本API，同时修正你当前的ADF结构错误：你之前的结构缺少paragraph块级节点，且数组闭合语法错误，正确的ADF格式传参示例如下：

{
    "fields": {
        "project": {
            "key": "你的项目key"
        },
        "summary": "工单标题",
        "description": {
            "type": "doc",
            "version": 1,
            "content": [
                {
                    "type": "paragraph",
                    "content": [
                        {
                            "type": "text",
                            "text": "你的描述文本内容，支持富文本格式配置"
                        }
                    ]
                }
            ]
        },
        "issuetype": {
            "name": "任务"
        }
        // 其余自定义字段等参数
    }
}