Issue description support of Atlassian Document Format (ADF)

[cacack]

Bug summary

Per the documentation https://jira.readthedocs.io/examples.html#working-with-rich-text

You can use rich text in an issue’s description or comment. In order to use rich text, the body content needs to be formatted using the Atlassian Document Format (ADF)

However, passing in a dictionary for the description field on an issue throws a error indicating the description must be a string. The source does type this as a string https://github.com/pycontribs/jira/blob/main/jira/resources.py#L761, so I suspect the documentation is incorrect and ADF can't (currently) be used for descriptions. If so, then would like to raise this as a bug to have ADF correctly supported for descriptions.

Is there an existing issue for this?

• I have searched the existing issues

Jira Instance type

Jira Cloud (Hosted by Atlassian)

Jira instance version

No response

jira-python version

3.6.0

Python Interpreter version

3.11.4

Which operating systems have you used?

• Linux
• macOS
• Windows

Reproduction steps

# 1. Given a Jira client instance
jira: JIRA
# 2. And given dictionary containing the ADF

rich_text = {
    "type": "doc",
    "version": 1,
    "content": [
      {
        "type": "codeBlock",
        "content": [
          {
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.",
            "type": "text"
          }
        ]
      }
    ]
  }

# 3. And given a dictionary contain the issue contents using the rich_text above.

issue_contents = {
    "project": {"id": "12345"},
    "issuetype": {"name": "Story"},
    "summary": "This is a test",
    "description": rich_text,
}

# 2. When I call the function using the issue_contents dictionary above.
issue = jira.create_issue(fields=issue_contents)

# 3. The JIRAError exception is thrown:
response text = {"errorMessages":[],"errors":{"description":"Operation value must be a string"}}

Stack trace

response text = {"errorMessages":[],"errors":{"description":"Operation value must be a string"}}

Expected behaviour

The issue is created using the ADF specified for the description.

Additional Context

No response

[heyeddi]

I got this same problem.
The reason is this library uses API version 2, to be able to use ADF it needs to be updated to version 3.

I found a way to update it when creating the Jira Client, however you must test if the v3 api is compatible with your code.

This is how I did it

class JiraClient():
    def __init__(self, jira_url: str, jira_username: str, jira_token: str):
        self.jira = JIRA(jira_url, basic_auth=(jira_username, jira_token))
        # update API version
        self.jira._options.update({"rest_api_version": 3})

after having that, you can test if the URL was updated with

client = JiraClient(jira_url=JIRA_URL,
                      jira_username=JIRA_USER,
                      jira_token=JIRA_TOKEN)

client.jira._get_url("issue")

Currently I only use create_issue and delete_issue, also update labels and add watches and that was compatible without changing anything in my code.

[saily]

If you use @heyeddi's approach, instanciating the class will call https://.../rest/api/2/serverInfo, as you see - still using version 2. Later API calls will then use the updated version 3.

A better way is to pass the options directly to the constructor, see below:

from jira import JIRA

client = JIRA(server=JIRA_URL,
              basic_auth=(JIRA_USER, JIRA_TOKEN),
              options={"rest_api_version": 3})

I'm still confused why version 2 is the default version still. This should be changed and added to the documentation.