Jira APIを使用する際、
チケットの説明文に、単純なテキスト以外にもリスト形式やコードブロックを使用すれば、よりわかりやすく記述が可能です。

こちらでチケットの作成コードを紹介しているので組み合わせて活用しましょう！

リッチテキストとは

リッチテキストとは、文字装飾や構造的な要素を用いて、単純なプレーンテキスト（無装飾の文字列）よりも視覚的に情報をわかりやすく伝えることを目的としたフォーマットです

Jira リッチテキスト仕様の`type`一覧

Jira のリッチテキストは、JSON データ形式で記述されます。この形式を利用して、Jira APIのdescriptionフィールドに構造的なデータを追加できます。

type	説明	オプション
text	テキストの装飾やリンク	装飾（太字、斜体など）が可能。
paragraph	一般的な説明文や文章	通常のテキストを含むブロック要素。
heading	セクションの見出し	`attrs.level`で階層（1～6）を指定可能。
listItem	リスト内の各項目	`bulletList`や`orderedList`内で使用。
bulletList	箇条書きリスト	順序なしリスト
orderedList	番号付きリスト	順序付きリスト（番号付き）
codeBlock	コードスニペット	コードを記述する。
blockquote	引用	引用文や注釈を記述する。
expand	展開	折りたたみ可能なセクション。
rule	水平線（区切り線）	内容を分割するための区切りを挿入する。
media	画像やファイル	Jiraにアップロードされたメディア（画像やファイル）。
panel	強調表示用のパネル	種類（情報、成功、エラーなど）を指定。
hardBreak	改行	明示的に改行を挿入する。

1. `text`

概要

段落や他の構造内で使用する基本的なテキスト要素。

構造例

{
  "type": "text",
  "text": "ノーマルテキスト",
  "marks": [
    { "type": "strong" },
    { "type": "em" }
  ]
}

用途

他のタイプ（paragraph, heading など）内で使用される基本テキスト。
マークアップ（太字、斜体など）を適用可能。

2. `paragraph`

概要

通常の段落を表現します。

構造例

{
  "type": "paragraph",
  "content": [
    { "type": "text", "text": "段落のテキスト." }
  ]
}

用途

一般的なテキストコンテンツ。
タスクや説明文などに使用。

3. `heading`

概要

見出しを表現します。

構造例

{
  "type": "heading",
  "attrs": { "level": 1 },
  "content": [
    { "type": "text", "text": "見出しのテキスト" }
  ]
}

用途

内容をセクション化する際の見出し。
attrs.level で階層（1～6）を指定、h1 ~ h6のことですね。

5. `bulletList`

概要

順序なしリストを表現します。

構造例

{
  "type": "bulletList",
  "content": [
    { "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "箇条書き1" }] }] },
    { "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "箇条書き2" }] }] }
  ]
}

用途

順序なしリスト（点やハイフン）で項目を表示。

6. `orderedList`

概要

順序付きリストを表現します。

構造例

{
  "type": "orderedList",
  "attrs": { "order": 1 },
  "content": [
    { "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "番号付きリスト1" }] }] },
    { "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "番号付きリスト2" }] }] }
  ]
}

用途

順序付きリスト（番号付き）で項目を表示。

7. `codeBlock`

概要

コードスニペットを表現します。

構造例

{
  "type": "codeBlock",
  "attrs": { "language": "javascript" },
  "content": [
    { "type": "text", "text": "console.log('Hello, world!');" }
  ]
}

用途

プログラムコードやスニペットを表示。

8. `blockquote`

概要

引用ブロックを表現します。

構造例

{
  "type": "blockquote",
  "content": [
    { "type": "paragraph", "content": [{ "type": "text", "text": "引用のテキスト。" }] }
  ]
}

用途

引用や注釈を表現。

9. `expand`

概要

展開可能なセクションを表現します。

構造例

{
  "type": "expand",
  "attrs": { "title": "詳細" },
  "content": [
    { "type": "paragraph", "content": [{ "type": "text", "text": "ここに詳細情報が表示されます。" }] }
  ]
}

用途

折りたたみ可能な詳細情報を提供。

10. `rule`

概要

水平線（ルール）を表現します。

構造例

{
  "type": "rule"
}

用途

内容を分割するための水平線。

11. `media`

概要

メディア（画像やファイル）を埋め込みます。
ローカルからアップロードが出来ず、既にjiraにアップロードした画像からIDを取得する形で記載するそうです。ちょっと使い勝手が悪いですかね。

構造例

{
  "type": "media",
  "attrs": {
    "type": "file",
    "id": "file-id",
    "collection": "media-collection"
  }
}

用途

画像やファイルを表示。

12. `panel`

概要

色付きの枠（パネル）で情報を強調します。

構造例

{
  "type": "panel",
  "attrs": { "panelType": "info" },

  "content": [
    { "type": "paragraph", "content": [{ "type": "text", "text": "情報パネルのテキスト" }] }
  ]
}

用途

情報、注意、エラーなどを強調。
panelTypeをinfo, success, warning, note, errorで指定できる。

13. `hardBreak`

概要

改行を表現します。

構造例

{
  "type": "paragraph",
  "content": [
    { "type": "text", "text": "これは改行が含まれるテキストです。" },
    { "type": "hardBreak" },
    { "type": "text", "text": "改行後のテキスト。" }
  ]
}

用途

文中で明示的な改行を挿入。

まとめ

これらのタイプを組み合わせることで、Jira API のリッチテキストを活用して、説明文やコメントに豊富な表現を追加できます。例えば、paragraph、codeBlock、expand を組み合わせて、以下のような説明文を構築できます。

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [{ "type": "text", "text": "Main description here." }]
    },
    {
      "type": "expand",
      "attrs": { "title": "Details" },
      "content": [
        { "type": "paragraph", "content": [{ "type": "text", "text": "Hidden details here." }] }
      ]
    },
    {
      "type": "codeBlock",
      "attrs": { "language": "ruby" },
      "content": [
        { "type": "text", "text": "def example_method\n  puts 'Hello, World!'\nend" }
      ]
    }
  ]
}

これを使えば、Jira のリッチテキストで柔軟な表現が可能です！